---
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
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an API key"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api_key"}
  context={"endpoint"}
>
  
</MethodEndpoint>



Creates a new API key.


<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"required":["name","grants"],"properties":{"name":{"type":"string","description":"A descriptive name for the API key.","example":"my-machine-process-that-will-access-nullplatform"},"grants":{"type":"array","description":"Defines access grants for an API key.\n\n> **Note**: Specify either `role_id` or `role_slug`, but not both.\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"}]}},"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"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"The operation was successful.","content":{"application/json":{"schema":{"type":"object","required":["id","name","tags","grants","created_at","updated_at","api_key"],"properties":{"id":{"type":"integer","description":"Unique ID for the API key.","example":1234},"name":{"type":"string","description":"The descriptive name given to the API key.","example":"CI/CD Main"},"api_key":{"type":"string","description":"Your newly created API key.\n\n>\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.","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.","example":1855672260},"role_slug":{"type":"string","description":"The slug of the role assigned to the API key for this NRN.","example":"machine:ci"}}}},"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."}}}}}}}}
>
  
</StatusCodes>