--- type: api title: Create API key description: Creates a new API key. url: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/cloud-enterprise/operation/operation-create-api-key resource: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/cloud-enterprise/operation/operation-create-api-key products: - Elastic Cloud Enterprise --- # Create API key Authentication: required ## Paths - `POST` `/users/auth/keys` ## Description Creates a new API key. ## Request body The request to create the API key `application/json` - `description` (string) — required API key description. Useful if there are multiple keys - `expiration` (string) — optional The optional expiration for the API key, provided as a duration (ex: '1d', '3h') - `role_assignments` (object) — optional Roles assigned to users, API keys or organization invitations. Currently unavailable in self-hosted ECE. - `platform` (object[]) — optional Assignments for roles with platform scope. - `role_id` (string) — required The ID of the role that is assigned. - `organization` (object[]) — optional Assignments for roles with organization scope. - `role_id` (string) — required The ID of the role that is assigned. - `organization_id` (string) — required The ID of the organization the role is scoped to. - `application_roles` (string[]) — optional If provided, the user assigned this role assignment will be granted this application role when signing in to a deployment or project - `deployment` (object[]) — optional Assignments for roles with deployment scope. - `role_id` (string) — required The ID of the role that is assigned. - `organization_id` (string) — required The ID of the organization the role is scoped to. - `all` (boolean) — optional When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in `deployment_ids`. - `deployment_ids` (string[]) — optional The IDs of the deployments the role is scoped to. Must be absent if `all` is true, and present if `all` is false. - `application_roles` (string[]) — optional If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment. - `project` (object) — optional Assignments for roles with project scope. - `elasticsearch` (object[]) — optional The Elasticsearch project-scoped role assignments to set - `role_id` (string) — required The ID of the role that is assigned. - `organization_id` (string) — required The ID of the organization the role is scoped to. - `all` (boolean) — optional When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in `project_ids`. - `project_ids` (string[]) — optional The IDs of the projects the role is scoped to. Must be absent if `all` is true, and present if `all` is false. - `application_roles` (string[]) — optional If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment. - `observability` (object[]) — optional The Observability project-scoped role assignments to set - `role_id` (string) — required The ID of the role that is assigned. - `organization_id` (string) — required The ID of the organization the role is scoped to. - `all` (boolean) — optional When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in `project_ids`. - `project_ids` (string[]) — optional The IDs of the projects the role is scoped to. Must be absent if `all` is true, and present if `all` is false. - `application_roles` (string[]) — optional If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment. - `security` (object[]) — optional The Security project-scoped role assignments to set - `role_id` (string) — required The ID of the role that is assigned. - `organization_id` (string) — required The ID of the organization the role is scoped to. - `all` (boolean) — optional When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in `project_ids`. - `project_ids` (string[]) — optional The IDs of the projects the role is scoped to. Must be absent if `all` is true, and present if `all` is false. - `application_roles` (string[]) — optional If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment. - `workplaceai` (object[]) — optional The WorkplaceAI project-scoped role assignments to set - `role_id` (string) — required The ID of the role that is assigned. - `organization_id` (string) — required The ID of the organization the role is scoped to. - `all` (boolean) — optional When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in `project_ids`. - `project_ids` (string[]) — optional The IDs of the projects the role is scoped to. Must be absent if `all` is true, and present if `all` is false. - `application_roles` (string[]) — optional If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment. ## Responses #### `201` The API key is created and returned in the body of the response. `application/json` - `id` (string) The API key ID. - `user_id` (string) The user ID. - `organization_id` (string) The organization ID linked to the API key - `description` (string) The API key description. TIP: Useful when you have multiple API keys. - `key` (string) The API key. TIP: Since the API key is returned only once, save it in a safe place. - `creation_date` (string · format: date-time) The date/time for when the API key is created. - `expiration_date` (string · format: date-time) The date/time when the API key expires. - `role_assignments` (object) Roles assigned to users, API keys or organization invitations. Currently unavailable in self-hosted ECE. Same fields as `role_assignments` #### `400` The request is invalid. Specify a different request, then try again. (code: `api_keys.invalid_input`) `application/json` - `errors` (object[]) A list of errors that occurred in the failing request - `code` (string) A structured code representing the error type that occurred - `message` (string) A human readable message describing the error that occurred - `fields` (string[]) If the error can be tied to a specific field or fields in the user request, this lists those fields ##### Response headers - `x-cloud-error-codes` (enum) The error codes associated with the response ## Code examples #### curl ```curl curl -X POST "${API_URL}/users/auth/keys" \ -u "${USERNAME}:${PASSWORD}" \ -H "Content-Type: application/json" \ -d '{ "description": "string" }' ``` ## Response examples #### 201 `application/json` Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields. ```json { "id": "string", "user_id": "string", "organization_id": "string", "description": "string", "key": "string", "creation_date": "string", "expiration_date": "string", "role_assignments": { "platform": [ { "role_id": "string" } ], "organization": [ { "role_id": "string", "organization_id": "string", "application_roles": [ "string" ] } ], "deployment": [ { "role_id": "string", "organization_id": "string", "all": false, "deployment_ids": [ "string" ], "application_roles": [ "string" ] } ], "project": { "elasticsearch": [ { "role_id": "string", "organization_id": "string", "all": false, "project_ids": [ "string" ], "application_roles": [ "string" ] } ], "observability": [ { "role_id": "string", "organization_id": "string", "all": false, "project_ids": [ "string" ], "application_roles": [ "string" ] } ], "security": [ { "role_id": "string", "organization_id": "string", "all": false, "project_ids": [ "string" ], "application_roles": [ "string" ] } ], "workplaceai": [ { "role_id": "string", "organization_id": "string", "all": false, "project_ids": [ "string" ], "application_roles": [ "string" ] } ] } } } ``` #### 400 `application/json` Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields. ```json { "errors": [ { "code": "string", "message": "string", "fields": [ "string" ] } ] } ```