--- type: api title: Get API key information description: Retrieves information for one or more API keys. url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-security-get-api-key resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-security-get-api-key products: - Elasticsearch Serverless --- # Get API key information Availability: ## Paths - `GET` `/_security/api_key` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/authentication#apikeyauth) ## Description Retrieves information for one or more API keys. NOTE: If you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own. If you have `read_security`, `manage_api_key` or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership. ## Required authorization * Cluster privileges: `manage_own_api_key`,`read_security` ## Query String Parameters - `id` (string Id) An API key id. This parameter cannot be used with any of `name`, `realm_name` or `username`. - `name` (string Name) An API key name. This parameter cannot be used with any of `id`, `realm_name` or `username`. It supports prefix search with wildcard. - `owner` (boolean · default: false) A boolean flag that can be used to query API keys owned by the currently authenticated user. The `realm_name` or `username` parameters cannot be specified when this parameter is set to `true` as they are assumed to be the currently authenticated ones. - `realm_name` (string Name) The name of an authentication realm. This parameter cannot be used with either `id` or `name` or when `owner` flag is set to `true`. - `username` (string) The username of a user. This parameter cannot be used with either `id` or `name` or when `owner` flag is set to `true`. - `with_limited_by` (boolean · default: false) Return the snapshot of the owner user's role descriptors associated with the API key. An API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors. - `active_only` (boolean · default: false) A boolean flag that can be used to query API keys that are currently active. An API key is considered active if it is neither invalidated, nor expired at query time. You can specify this together with other parameters such as `owner` or `name`. If `active_only` is false, the response will include both active and inactive (expired or invalidated) keys. - `with_profile_uid` (boolean · default: false) Determines whether to also retrieve the profile uid, for the API key owner principal, if it exists. ## Response `application/json` - `api_keys` ([] ApiKey) - `id` (string Id) Id for the API key - `name` (string Name) Name of the API key. - `type` (enum ApiKeyType) The type of the API key (e.g. `rest` or `cross_cluster`). Values: `rest`, `cross_cluster` - `creation` (EpochTimeUnitMillis) Creation time for the API key in milliseconds. - `expiration` (EpochTimeUnitMillis) Expiration time for the API key in milliseconds. - `invalidated` (boolean) Invalidation status for the API key. If the key has been invalidated, it has a value of `true`. Otherwise, it is `false`. - `invalidation` (EpochTimeUnitMillis) If the key has been invalidated, invalidation time in milliseconds. - `username` (string) Principal for which this API key was created - `realm` (string) Realm name of the principal for which this API key was created. - `realm_type` (string) Realm type of the principal for which this API key was created - `metadata` (Metadata) Metadata of the API key - `role_descriptors` (map string to RoleDescriptor) The role descriptors assigned to this API key when it was created or last updated. An empty role descriptor means the API key inherits the owner user’s permissions. Map values ({} RoleDescriptor) - `cluster` ([] union ClusterPrivilege) A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute. Values: `all`, `cancel_task`, `manage`, `manage_api_key`, `manage_behavioral_analytics`, `manage_enrich`, `manage_esql`, `manage_index_templates`, `manage_inference`, `manage_ingest_pipelines`, `manage_logstash_pipelines`, `manage_ml`, `manage_own_api_key`, `manage_pipeline`, `manage_reindex`, `manage_search_application`, `manage_search_query_rules`, `manage_search_synonyms`, `manage_security`, `manage_transform`, `monitor`, `monitor_enrich`, `monitor_esql`, `monitor_inference`, `monitor_ml`, `monitor_reindex`, `monitor_transform`, `none`, `post_behavioral_analytics_event`, `read_pipeline`, `read_security`, `read_project_routing`, `manage_project_routing` - `indices` ([] IndicesPrivileges) A list of indices permissions entries. - `field_security` ({} FieldSecurity) The document fields that the owners of the role have read access to. - `except` (string Fields) - `grant` (string Fields) - `names` (union IndexName | [] IndexName) A list of indices (or index name patterns) to which the permissions in this entry apply. - `privileges` ([] union IndexPrivilege) The index level privileges that owners of the role have on the specified indices. Values: `all`, `auto_configure`, `create`, `create_doc`, `create_index`, `create_view`, `delete`, `delete_index`, `delete_view`, `index`, `maintenance`, `manage`, `manage_data_stream_lifecycle`, `manage_view`, `monitor`, `none`, `read`, `read_view_metadata`, `view_index_metadata`, `write` - `query` (IndicesPrivilegesQuery) A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role. - `applications` ([] ApplicationPrivileges) A list of application privilege entries - `application` (string) The name of the application to which this entry applies. - `privileges` ([] string) A list of strings, where each element is the name of an application privilege or action. - `resources` ([] string) A list resources to which the privileges are applied. - `metadata` (Metadata) Optional meta-data. Within the metadata object, keys that begin with `_` are reserved for system usage. - `run_as` ([] string) A list of users that the API keys can impersonate. NOTE: In Elastic Cloud Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty `run_as` field, but a non-empty list will be rejected. - `description` (string) Optional description of the role descriptor - `restriction` ({} Restriction) Restriction for when the role descriptor is allowed to be effective. - `workflows` ([] union RestrictionWorkflow) A list of workflows to which the API key is restricted. NOTE: In order to use a role restriction, an API key must be created with a single role descriptor. Values: `search_application_query` - `transient_metadata` (map string to object) - `limited_by` ([] string to RoleDescriptor) The owner user’s permissions associated with the API key. It is a point-in-time snapshot captured at creation and subsequent updates. An API key’s effective permissions are an intersection of its assigned privileges and the owner user’s permissions. - `access` ({} Access) The access granted to cross-cluster API keys. The access is composed of permissions for cross cluster search and cross cluster replication. At least one of them must be specified. When specified, the new access assignment fully replaces the previously assigned access. - `replication` ([] ReplicationAccess) A list of indices permission entries for cross-cluster replication. - `names` (union IndexName | [] IndexName) A list of indices (or index name patterns) to which the permissions in this entry apply. - `allow_restricted_indices` (boolean · default: false) This needs to be set to true if the patterns in the names field should cover system indices. - `search` ([] SearchAccess) A list of indices permission entries for cross-cluster search. - `field_security` ({} FieldSecurity) The document fields that the owners of the role have read access to. - `except` (string Fields) - `grant` (string Fields) - `names` (union IndexName | [] IndexName) A list of indices (or index name patterns) to which the permissions in this entry apply. - `query` (IndicesPrivilegesQuery) A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role. - `profile_uid` (string) The profile uid for the API key owner principal, if requested and if it exists - `_sort` (SortResults) Sorting values when using the `sort` parameter with the `security.query_api_keys` API. ## Code Examples #### Console ```console GET /_security/api_key?username=myuser&realm_name=native1 ``` #### JavaScript ```javascript const response = await client.security.getApiKey({ username: "myuser", realm_name: "native1", }); ``` #### Python ```python resp = client.security.get_api_key( username="myuser", realm_name="native1", ) ``` #### curl ```curl curl -X GET "$ELASTICSEARCH_URL/_security/api_key?username=myuser&realm_name=native1" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" ``` #### Java ```java client.security().getApiKey(g -> g .realmName("native1") .username("myuser") ); ``` #### C# ```c# var response = await client.Security .GetApiKeyAsync(d1 => d1 .RealmName("native1") .Username("myuser") ); ``` #### PHP ```php $resp = $client->security()->getApiKey([ "username" => "myuser", "realm_name" => "native1", ]); ``` #### Ruby ```ruby response = client.security.get_api_key( username: "myuser", realm_name: "native1" ) ``` ## Response Examples #### Get a key by ID A successful response from `GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&with_limited_by=true`. ```json { "api_keys": [ { "id": "VuaCfGcBCdbkQm-e5aOx", "name": "my-api-key", "creation": 1548550550158, "expiration": 1548551550158, "invalidated": false, "username": "myuser", "realm": "native1", "realm_type": "native", "metadata": { "application": "myapp" }, "role_descriptors": { }, "limited_by": [ { "role-power-user": { "cluster": [ "monitor" ], "indices": [ { "names": [ "*" ], "privileges": [ "read" ], "allow_restricted_indices": false } ], "applications": [ ], "run_as": [ ], "metadata": { }, "transient_metadata": { "enabled": true } } } ] } ] } ``` #### Get all keys for a user A successful response from `GET /_security/api_key?username=myuser&realm_name=native1`. The response contains all API keys for the user `myuser` in the `native1` realm. ```json { "api_keys": [ { "id": "0GF5GXsBCXxz2eDxWwFN", "name": "hadoop_myuser_key", "creation": 1548550550158, "expiration": 1548551550158, "invalidated": false, "username": "myuser", "realm": "native1", "realm_type": "native", "metadata": { "application": "myapp" }, "role_descriptors": { "role-a": { "cluster": [ "monitor" ], "indices": [ { "names": [ "index-a" ], "privileges": [ "read" ], "allow_restricted_indices": false } ], "applications": [ ], "run_as": [ ], "metadata": { }, "transient_metadata": { "enabled": true } } } }, { "id": "6wHJmcQpReKBa42EHV5SBw", "name": "api-key-name-2", "creation": 1548550550158, "invalidated": false, "username": "user-y", "realm": "realm-2", "metadata": {}, "role_descriptors": { } } ] } ```