| mapped_pages | |||||||
|---|---|---|---|---|---|---|---|
| applies_to |
|
||||||
| products |
|
{{ecloud}} API keys allow you to programmatically access the following resources:
- {{ecloud}} APIs
- {{ecloud}} {{serverless-short}} APIs
- {applies_to}
serverless: gaOptionally, {{es}} {{serverless-full}} and {{kib}} {{serverless-full}} APIs
Only Organization owners can create and manage API keys. An API key is not tied to the user who created it. When creating a key, you assign it specific roles to control its access to organizational resources, including hosted deployments and serverless projects. If a user leaves the organization, the API keys they have created will still function until they expire.
You can have multiple API keys for different purposes, and you can revoke them when you no longer need them. Each organization can have up to 500 active API keys.
:::{agent-skill} :url: https://github.com/elastic/agent-skills/tree/main/skills/cloud/access-management :::
:::{admonition} {{es}} and {{kib}} API access :applies_to: ech:
By default, {{ecloud}} API keys provide access to the APIs for managing your organization, deployments, and projects.
In {{ech}} deployments, {{ecloud}} API keys do not provide access to {{es}} or {{kib}} APIs. Learn how to create an {{es}} API key for ECH deployments.
In the case of {{serverless-full}} projects, you can optionally grant access to {{es}} {{serverless-short}} and {{kib}} {{serverless-short}} APIs when you assign roles to the API key. :::
::::{tab-set} :::{tab-item} Using the {{ecloud}} Console
- Log in to the {{ecloud}} Console.
- Go to your avatar in the upper right corner and choose Organization.
- On the API keys tab of the Organization page, click Create API key.
- On the Create API key flyout, you can configure your new key:
- Add a unique name for the key.
- Set the expiration for the key.
- Assign roles.
- Click Create API key, copy the generated API key, and store it in a safe place. You can also download the key as a CSV file.
The API key needs to be supplied in the Authorization header of a request, in the following format:
Authorization: ApiKey $EC_API_KEY::: :::{tab-item} Using the {{ecloud}} API
You can create an API key using the Create API key API.
curl -XPOST \
-H 'Content-Type: application/json' \
-H "Authorization: ApiKey $EC_API_KEY" \
"https://api.elastic-cloud.com/api/v1/users/auth/keys
{
"description": "api-created-key",
"expiration": "90d",
"role_assignments": {
"project": {
"elasticsearch": [
{
"role_id": "elasticsearch-admin",
"organization_id": "ORG_ID_PLACEHOLDER",
"all": false,
"project_ids": [
"PROJECT_ID_PLACEHOLDER"
],
"application_roles": [
"admin"
] <1>
}
]
}
}
}- Roles granted for project-level access through the {{es}} and {{kib}} APIs. ::: ::::
- Log in to {{ecloud}}.
- From the navigation menu, select Organization > API keys.
- Find the key you want to revoke, and click the trash icon under Actions.
By default, API keys expire after three months. You can set the expiration to a different preset value or to a specific date, up to one year. If you need the key to work indefinitely, you can set its expiration to Never.
When an API key is nearing expiration, Elastic sends an email to the creator of the API key and each of the operational contacts. When you use an API key to authenticate, the API response header X-Elastic-Api-Key-Expiration indicates the key’s expiration date. You can log this value to detect API keys that are nearing expiration.
When an API key expires, it is automatically removed from the API keys tab.
Roles grant an API key specific privileges for your {{ecloud}} organization and resources.
You can grant a cloud API key the same types of roles that you assign to users: organization-level roles, cloud resource access roles, and connected cluster access roles.
serverless: ga
When you grant Organization owner access, or Cloud resource access for one or more {{serverless-short}} projects, you can select your level of API access:
| Access | Grant |
|---|---|
| Cloud API (default) | Grants access to only {{ecloud}} and {{ecloud}} {{serverless-short}} APIs. No direct access to project {{es}} or {{kib}} API endpoints. |
| Cloud, {{es}}, and {{kib}} API | Grants the following access: • {{ecloud}} and {{ecloud}} {{serverless-short}} APIs • {{es}} {{serverless-short}}, and {{kib}} {{serverless-short}} API endpoints for the relevant projects |
Using {{ecloud}} keys for project-level API access, rather than granting keys from within each {{serverless-short}} project, allows you to create keys that can interact with multiple projects, and manage API access centrally from the {{ecloud}} console.
:::{important} :applies_to: serverless: preview The cross-project search feature requires {{ecloud}} API keys for programmatic access. :::
When granting Cloud resource access, you can apply a predefined role or custom role to granularly control access to the specified resources. The selected role controls access to resources in all relevant APIs.
All roles include permissions for Cloud APIs, as well as {{es}} and {{kib}} APIs. Your API access selection limits the role's scope and can disable core functionality:
-
Cloud API access: The API key can use the role’s permissions for organization-level actions in {{ecloud}}, but it has no direct access to the project itself. Roles designed for project use, such as the Security Tier 1 analyst role, have only Viewer access to the relevant projects through {{ecloud}} APIs.
API keys with custom roles are also limited to Viewer access in the project.
-
Cloud, {{es}}, and {{kib}} API access: The API key can use the role’s permissions to fully interact with the project. This selection is required for custom roles to work as intended, because they rely on the {{es}} and {{kib}} serverless APIs for project-level access.
For details on the permissions granted for each role, refer to the predefined roles table.