Retrieve an API Key

This API is used to retrieve a single API Key by unique Id. To retrieve a key, an API key with equal or greater permissions must be used.

Retrieve an API Key by unique Id

GET/api/api-key/{keyId}

OpenAPI Spec

Request#

Request Parameters#

apiKeyIdUUIDrequired

The unique Id of the API Key to retrieve.

Response#

The response for this API contains a single API Key. The response is defined below along with an example JSON response.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

apiKey.expirationInstantLongAvailable since 1.55.0

The expiration instant of this API key. Using an expired API key for API Authentication will result in a 401 response code.

apiKey.idUUID

The Id of the API key.

apiKey.insertInstantLong

The instant when the API key was added to the FusionAuth database.

apiKey.ipAccessControlListIdUUIDAvailable since 1.30.0

The Id of the IP Access Control List limiting access to this API key.

apiKey.keyString

The API key value, this is the string value you will use in the Authorization header to authenticate API requests.

If the apiKey.retrievable value is false then this field will not be returned in the response.

apiKey.keyManagerBoolean

Indicates whether this key is a key manager. Setting this flag to true allows this key to be used to call these APIs. An attempt to call these APIs with a non-manager key (keyManager set to false) will always return a HTTP response status code 401.

apiKey.lastUpdateInstantLong

The instant when the API key was last updated in the FusionAuth database.

apiKey.metaData.attributes.descriptionString

Description of the key.

apiKey.nameStringAvailable since 1.56.0

The name of the API key.

apiKey.permissions.endpointsObject

Endpoint permissions for this key. Each key of the object is an endpoint, with the value being an array of the HTTP methods which can be used against the endpoint. An empty permissions object mean that this is a super key that authorizes this key for all the endpoints.

apiKey.retrievableBooleanAvailable since 1.56.0

Indicates whether this key is retrievable. If this value is false, the key will not be returned in the API response.

apiKey.tenantIdString

The unique Id of the Tenant. This value is present if the key is tenant scoped. Tenant scoped keys can only be used to access users and other tenant scoped objects for the specified tenant. This value is read-only once the key is created.

Example API Key response JSON

{
  "apiKey": {
    "expirationInstant": 872812800000,
    "id": "b016fa93-e8bc-4b79-b39f-5d37966c0178",
    "insertInstant": 1619119404194,
    "ipAccessControlListId": "eae37b0e-950b-4e92-abcc-d0b310326f66",
    "key": "WHYugARKzum-jHvzCk5-C558EKPaYEECz5k8fDZayIaFiZHRKqy9kaQn",
    "keyManager": false,
    "lastUpdateInstant": 1619120513500,
    "metaData": {
      "attributes": {
        "description": "non-manager key"
      }
    },
    "name": "Awesome API Key",
    "permissions": {
      "endpoints": {
        "/api/application": [
          "DELETE",
          "POST",
          "GET",
          "PUT",
          "PATCH"
        ],
        "/api/application/oauth-configuration": [
          "DELETE",
          "POST",
          "GET",
          "PUT",
          "PATCH"
        ],
        "/api/application/role": [
          "DELETE",
          "POST",
          "GET",
          "PUT",
          "PATCH"
        ]
      }
    },
    "retrievable": true,
    "tenantId": "94f751c5-4883-4684-a817-6b106778edec"
  }
}