--- 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/operation/operation-security-get-api-key resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-security-get-api-key products: - Elasticsearch --- # Get API key information Availability: 6.7+ ## Paths - `GET` `/_security/api_key` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth) ## 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`, `clone_api_key`, `create_snapshot`, `cross_cluster_replication`, `cross_cluster_search`, `delegate_pki`, `grant_api_key`, `manage`, `manage_api_key`, `manage_autoscaling`, `manage_behavioral_analytics`, `manage_ccr`, `manage_data_frame_transforms`, `manage_data_stream_global_retention`, `manage_enrich`, `manage_esql`, `manage_ilm`, `manage_index_templates`, `manage_inference`, `manage_ingest_pipelines`, `manage_logstash_pipelines`, `manage_ml`, `manage_oidc`, `manage_own_api_key`, `manage_pipeline`, `manage_reindex`, `manage_rollup`, `manage_saml`, `manage_search_application`, `manage_search_query_rules`, `manage_search_synonyms`, `manage_security`, `manage_service_account`, `manage_slm`, `manage_token`, `manage_transform`, `manage_user_profile`, `manage_watcher`, `monitor`, `monitor_data_frame_transforms`, `monitor_data_stream_global_retention`, `monitor_enrich`, `monitor_esql`, `monitor_inference`, `monitor_ml`, `monitor_reindex`, `monitor_rollup`, `monitor_snapshot`, `monitor_stats`, `monitor_text_structure`, `monitor_transform`, `monitor_watcher`, `none`, `post_behavioral_analytics_event`, `read_ccr`, `read_fleet_secrets`, `read_ilm`, `read_pipeline`, `read_security`, `read_slm`, `transport_client`, `write_connector_secrets`, `write_fleet_secrets` - `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`, `cross_cluster_replication`, `cross_cluster_replication_internal`, `delete`, `delete_index`, `delete_view`, `index`, `maintenance`, `manage`, `manage_data_stream_lifecycle`, `manage_follow_index`, `manage_ilm`, `manage_leader_index`, `manage_view`, `monitor`, `none`, `read`, `read_cross_cluster`, `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. - `allow_restricted_indices` (boolean · default: false) Set to `true` if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the `names` list, Elasticsearch checks privileges against these indices regardless of the value set for `allow_restricted_indices`. - `remote_indices` ([] RemoteIndicesPrivileges) A list of indices permissions for remote clusters. - `clusters` (string Names) A list of cluster aliases to which the permissions in this entry apply. - `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`, `cross_cluster_replication`, `cross_cluster_replication_internal`, `delete`, `delete_index`, `delete_view`, `index`, `maintenance`, `manage`, `manage_data_stream_lifecycle`, `manage_follow_index`, `manage_ilm`, `manage_leader_index`, `manage_view`, `monitor`, `none`, `read`, `read_cross_cluster`, `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. - `allow_restricted_indices` (boolean · default: false) Set to `true` if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the `names` list, Elasticsearch checks privileges against these indices regardless of the value set for `allow_restricted_indices`. - `remote_cluster` ([] RemoteClusterPrivileges) A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions. - `clusters` (string Names) A list of cluster aliases to which the permissions in this entry apply. - `privileges` ([] enum RemoteClusterPrivilege) The cluster level privileges that owners of the role have on the remote cluster. Values: `monitor_enrich`, `monitor_stats` - `global` ({} GlobalPrivilege) An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. - `application` ({} ApplicationGlobalUserPrivileges) - `manage` ({} ManageUserPrivileges) - `applications` ([] string) - `profile` ({} WriteProfileGlobalUserPrivileges) A privilege that grants the ability to write the `data` and `access` sections of user profiles for the specified applications. - `write` ({} ManageUserPrivileges) The applications for which user profile data can be written. Absent when the `profile` section is present but grants no privileges. - `applications` ([] string) - `role` ({} ManageRolesGlobalUserPrivileges) A privilege that grants the ability to manage roles that are scoped to the specified indices. - `manage` ({} ManageRolesPrivileges) The index-scoped role management privileges. Absent when the `role` section is present but grants no privileges. - `indices` ([] ManageRolesIndexPermissions) - `names` ([] string) A list of indices (or index name patterns) that the owners of the role can manage roles for. - `privileges` ([] string) The index privileges that the managed roles are allowed to grant on the specified indices. - `data_source` ([] DataSourcePrivileges) A list of data source privilege entries, used to grant access to ES|QL data sources. - `names` ([] string) A list of data source names or wildcard patterns to which the permissions in this entry apply. - `privileges` ([] union DataSourcePrivilege) The data source privileges that owners of the role have for the specified data sources. Supported values include: - `create`: Grants privilege to create a data source with a matching name. - `delete`: Grants privilege to delete a data source with a matching name. - `read_metadata`: Grants privilege to read a data source's metadata. - `read`: Grants privilege to attach a dataset to a data source with a matching name. - `manage`: Grants all data source privileges, including `create`, `delete`, `read`, and `read_metadata`. Values: `create`, `delete`, `read_metadata`, `read`, `manage` - `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. - `allow_restricted_indices` (boolean · default: false) Set to `true` if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the `names` list, Elasticsearch checks privileges against these indices regardless of the value set for `allow_restricted_indices`. - `certificate_identity` (string) The certificate identity associated with a cross-cluster API key. Restricts the API key to connections authenticated by a specific TLS certificate. Only applicable to cross-cluster API keys. - `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": { } } ] } ```