---
id: api-key-create
title: Create an API key
description: Creates a new API key.
sidebar_label: Create an API key
hide_title: true
hide_table_of_contents: true
api: >-
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
sidebar_class_name: post api-method
info_path: docs/api/authorization
custom_edit_url: null
canonical: 'https://docs.nullplatform.com/docs/api/api-key-create'
---
Creates a new API key.
**Note**: Use `role_id` in every grant of a key, or `role_slug` in every grant,\n> never one in some and the other in others: every grant of a key is resolved the\n> same way.\n>\n","items":{"type":"object","oneOf":[{"type":"object","required":["nrn","role_slug"],"properties":{"nrn":{"type":"string","description":"The NRN of the resource where the API key's role is assigned.","example":"organization=1:account=1:namespace=1:application=4"},"role_slug":{"type":"string","description":"The slug of the role assigned to the API key for this NRN.\n\n> Note: See [Roles](/docs/authorization/roles) for more info.\n>\n","example":"machine:ci"}},"title":"grantsRoleSlug"},{"type":"object","required":["nrn","role_id"],"properties":{"nrn":{"type":"string","description":"The NRN of the resource where the API key's role is assigned.","example":"organization=1:account=1:namespace=1:application=4"},"role_id":{"type":"integer","description":"The ID of the role assigned to the API key for this NRN.\n\n> Note: See [Roles](/docs/authorization/roles) for more info.\n>\n","example":700317756}},"title":"grantsRoleId"},{"type":"object","required":["nrn","actions"],"properties":{"nrn":{"type":"string","description":"The NRN of the resource the grant applies to.","example":"organization=1:account=1:namespace=1"},"actions":{"type":"array","description":"The actions the API key may call at this NRN, without naming an existing role.\nnullplatform creates a role private to the key carrying exactly these actions.\n\n> Note: You can only grant actions you could hand out at that NRN yourself: the ones\n> you hold there, plus the ones carried by roles you may assign to an API key there.\n>\n","items":{"type":"string"},"example":["application:read","deployment:create"]}},"title":"grantsActions"},{"type":"object","required":["nrn","inherits"],"properties":{"nrn":{"type":"string","description":"The NRN of the resource the grant applies to.","example":"organization=1:account=1"},"inherits":{"type":"array","description":"Existing roles, by slug or ID, merged into a single role private to this key.\nInheriting two roles in one grant is not the same as granting them separately:\nit produces one role, which `actions.add` and `actions.remove` can then adjust.\nYou must be allowed to assign each inherited role to an API key at this NRN, the\nsame check a grant by `role_id` passes. The key follows the roles it inherits: an\naction later added to one of them reaches the key too.\n\n> Note: A role private to another API key cannot be inherited.\n>\n","items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"example":["ops","developer"]},"actions":{"type":"object","description":"How the union of the inherited roles is adjusted.","properties":{"add":{"type":"array","description":"Actions granted on top of what the inherited roles provide. Measured against what you can hand out at this NRN.","items":{"type":"string"},"example":["application:delete"]},"remove":{"type":"array","description":"Inherited actions excluded from this grant. Each must be carried by one of the inherited roles, and none may also be in `add`.","items":{"type":"string"},"example":["deployment:create"]}}}},"title":"grantsInherits"}]}},"tags":{"type":"array","description":"Tags associated with your API key.","items":{"type":"object","properties":{"key":{"type":"string","description":"Tag key associated with your API key.","example":"CI"},"value":{"type":"string","description":"Tag value associated with your API key.","example":"main"}}}}},"title":"api_keyNew"},"examples":{"Create API key using role_slug":{"value":{"name":"my-machine-process-that-will-access-nullplatform","grants":[{"nrn":"organization=1:account=1:namespace=1:application=4","role_slug":"machine:ci"}],"tags":[{"key":"machine","value":"true"}]}},"Create API key using role_id":{"value":{"name":"my-machine-process-that-will-access-nullplatform","grants":[{"nrn":"organization=1:account=1:namespace=1:application=4","role_id":1855672260}],"tags":[{"key":"machine","value":"true"}]}}}}}}}
>
\n> ⚠️ **Save your API key securely.**\n>\n>The API key value will be displayed only once. Make sure to store it in a secure location as it cannot be retrieved later.","example":"AAAA.1234567890abcdef1234567890abcdefPTs="},"masked_api_key":{"type":"string","description":"Your masked API key.","example":"AAAA.xxxxxxxxxxxxxxxxxxxxxPTs=","nullable":true},"tags":{"type":"array","description":"Array of tags associated with your API key.\n\nℹ️ If no tags are found, we return an empty array.\n","items":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string","description":"Tag key associated with your API key.","example":"CI"},"value":{"type":"string","description":"Tag value associated with your API key.","example":"main"}}}},"grants":{"type":"array","description":"Defines access grants for an API key. A grant created from `actions` or `inherits`\nreads back as the action names it resolved to; the role behind it is private to the\nkey and carries no meaning of its own.\n","items":{"type":"object","required":["nrn","role_id","role_slug"],"properties":{"nrn":{"type":"string","description":"The NRN of the resource where the API key's role is assigned.","example":"organization=1:account=1:namespace=1:application=4"},"role_id":{"type":"integer","description":"The ID of the role assigned to the API key for this NRN. For a grant created\nfrom `actions` or `inherits` this names a role private to the key, recreated\nwhenever the grants are replaced, so do not store it.\n","example":1855672260},"role_slug":{"type":"string","description":"The slug of the role assigned to the API key for this NRN. Private to the key,\nand not reusable, for a grant created from `actions` or `inherits`.\n","example":"machine:ci"},"actions":{"type":"array","description":"The action names this grant resolves to, present when the grant was created\nfrom `actions` or `inherits`. An action that has an alias is listed under the\nalias, not under the name it is stored as.\n","items":{"type":"string"},"example":["application:read","deployment:create"]},"inherits":{"type":"array","description":"The roles this grant merged. Present only for the `inherits` shape.","items":{"type":"object","properties":{"id":{"type":"integer","example":1855672260},"slug":{"type":"string","example":"ops"},"organization_id":{"type":"integer","example":1}}}},"added":{"type":"array","description":"The actions granted on top of what was inherited, as sent in `actions.add`.","items":{"type":"string"},"example":["application:delete"]},"removed":{"type":"array","description":"The inherited actions excluded, as sent in `actions.remove`.","items":{"type":"string"},"example":["deployment:create"]}}}},"owner_id":{"type":"integer","description":"The unique ID of the user that creates the API key.","example":1595},"last_used_at":{"type":"string","description":"The ISO-8601 UTC timestamp of when the API key was last used.","nullable":true,"format":"date-time","example":"2021-01-02T00:00:00Z"},"created_at":{"type":"string","description":"The ISO-8601 UTC timestamp of when the API key was created.","format":"date-time","example":"2021-01-02T00:00:00Z"},"updated_at":{"type":"string","description":"The ISO-8601 UTC timestamp of when the API key was last updated.","format":"date-time","example":"2021-01-02T00:00:00Z"}},"title":"apiKeyPostResponse"}}}},"4XX":{"description":"Client error responses due to invalid input or missing parameters.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific client error (e.g., 400, 401, 403, 404).","example":400},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"bad_request"},"error":{"type":"string","description":"A brief, human-readable description of the error type (e.g., \"Bad Request\", \"Unauthorized\").","example":"Bad Request"},"message":{"type":"string","description":"Additional details about the error.","example":"The request was malformed or contained invalid parameters."}}}}}},"5XX":{"description":"Server error responses indicating an issue on the API side.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific server error (e.g., 500, 502, 503).","example":500},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"internal_server_error"},"error":{"type":"string","description":"A brief, human-readable description of the error type (e.g., \"Internal Server Error\", \"Service Unavailable\").","example":"Internal Server Error"},"message":{"type":"string","description":"Additional details about the error.","example":"An unexpected error occurred. Please try again later."}}}}}}}}
>