API Key APIs

Overview

This API has been available since 1.26.0

The FusionAuth APIs are primarily secured using API keys. This API can only be accessed using an API key that has a keyManager attribute of true. In order to retrieve, update or delete an API key, an API key with equal or greater permissions must be used. A "tenant-scoped" API key can retrieve, create, update or delete an API key for the same tenant. This page describes APIs that are used to manage API keys.

Here’s a brief video covering the API keys API:

Please refer to the Authentication document for more details about using API keys.

The Key Manager Setting
Create an API Key
Create a New API Key From an Existing API Key
Retrieve an API Key
Update an API Key
Delete an API Key

The Key Manager Setting

This API can only be used by API keys with the Key manager setting enabled.

Below is an image of an API key being created in the administrative user interface with Key manager enabled:

For security purposes, the Key manager setting may be modified only using the administrative user interface or Kickstart. It can’t be changed using this API.

Create an API Key

This API is used to create a new API Key. An API key with key manager permission set to true can create keys. A key with key manager permissions can not be created using this API. Only through admin UI or kickstart, it is possible to create such a key. An API key that is tenant scoped, can create another key for the same tenant.

Create a new Key with the provided unique Id

URI

POST /api/api-key/{apiKeyId}

Request Parameters

apiKeyId [UUID] Optional defaults to a generated UUID: The unique Id of the API Key to create. If not specified a secure random UUID will be generated.

Request Body

apiKey.key [String] Optional

API key string. When you create an API key the key is defaulted to a secure random value but the API key is simply a string, so you may call it super-secret-key if you’d like. However a long and random value makes a good API key in that it is unique and difficult to guess.

apiKey.ipAccessControlListId [UUID] Optional Available since 1.30.0

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

Note: An Enterprise plan is required to utilize IP ACLs.

apiKey.metaData.attributes.description [String] Optional

Description of the key.

apiKey.permissions.endpoints [Object] Optional

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.tenantId [String] Optional

The unique Id of the Tenant. This value is required if the key is meant to be 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 request JSON


{
  "apiKey": {
    "key": "super-secret-key",
    "ipAccessControlListId": "eae37b0e-950b-4e92-abcc-d0b310326f66",
    "metaData": {
      "attributes": {
        "description": "my super secret key"
      }
    },
    "permissions": {
      "endpoints": {
        "/api/application": [
          "DELETE",
          "POST",
          "GET",
          "PUT",
          "PATCH"
        ]
      }
    },
    "tenantId": "94f751c5-4883-4684-a817-6b106778edec"
  }
}

Response

The response for this API contains the Key that was updated.

Table 1. 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.
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.id [UUID]: The Id of the API key.
apiKey.insertInstant [Long]: The instant when the API key was added to the FusionAuth database.
apiKey.ipAccessControlListId [UUID]: The Id of the IP Access Control List limiting access to this API key.
apiKey.key [String]: The API key value, this is the string value you will use in the Authorization header to authenticate API requests.
apiKey.keyManager [Boolean]: 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.lastUpdateInstant [Long]: The instant when the API key was last updated in the FusionAuth database.
apiKey.metaData.attributes.description [String]: Description of the key.
apiKey.permissions.endpoints [Object]: 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.tenantId [String]: The unique Id of the Tenant. This value is read-only once the key is created.

Example API Key Response JSON


{
  "apiKey": {
    "id": "de36ce0f-70db-4d73-b0b2-9f82c1572761",
    "insertInstant": 1619726194060,
    "ipAccessControlListId": "eae37b0e-950b-4e92-abcc-d0b310326f66",
    "key": "super-secret-key",
    "keyManager": false,
    "lastUpdateInstant": 1619726194060,
    "metaData": {
      "attributes": {
        "description": "my super secret key"
      }
    },
    "permissions": {
      "endpoints": {
        "/api/application": [
          "DELETE",
          "POST",
          "GET",
          "PUT",
          "PATCH"
        ]
      }
    },
    "tenantId": "94f751c5-4883-4684-a817-6b106778edec"
  }
}

Create a New API Key From an Existing API Key

This API is used to create a New API Key based on an existing API Key (source key). The API key that is being copied must not be set as a key manager, if it is, this API will return an error. The resulting new key will have the same permissions as the source key.

Create a new Key from an Existing Key

URI

POST /api/api-key/

Example API Key request JSON


{
  "sourceKeyId": "48b5762e-6829-4d7e-b53d-f7db5f5d3d1f"
}

Response

The response for this API contains the Key that was created.

Table 2. 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.
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.id [UUID]: The Id of the API key.
apiKey.insertInstant [Long]: The instant when the API key was added to the FusionAuth database.
apiKey.ipAccessControlListId [UUID]: The Id of the IP Access Control List limiting access to this API key.
apiKey.key [String]: The API key value, this is the string value you will use in the Authorization header to authenticate API requests.
apiKey.keyManager [Boolean]: 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.lastUpdateInstant [Long]: The instant when the API key was last updated in the FusionAuth database.
apiKey.metaData.attributes.description [String]: Description of the key.
apiKey.permissions.endpoints [Object]: 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.tenantId [String]: 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": {
    "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"
      }
    },
    "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"
        ]
      }
    },
    "tenantId": "94f751c5-4883-4684-a817-6b106778edec"
  }
}

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

URI

GET /api/api-key/{apiKeyId}

Request Parameters

apiKeyId [UUID] Required: 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.

Table 3. 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.id [UUID]: The Id of the API key.
apiKey.insertInstant [Long]: The instant when the API key was added to the FusionAuth database.
apiKey.ipAccessControlListId [UUID]: The Id of the IP Access Control List limiting access to this API key.
apiKey.key [String]: The API key value, this is the string value you will use in the Authorization header to authenticate API requests.
apiKey.keyManager [Boolean]: 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.lastUpdateInstant [Long]: The instant when the API key was last updated in the FusionAuth database.
apiKey.metaData.attributes.description [String]: Description of the key.
apiKey.permissions.endpoints [Object]: 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.tenantId [String]: 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": {
    "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"
      }
    },
    "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"
        ]
      }
    },
    "tenantId": "94f751c5-4883-4684-a817-6b106778edec"
  }
}

Update an API Key

This API is used to update an existing API Key. A tenant-scoped API key can update another API key for the same tenant.

Update the Key with the given Id

URI

PUT /api/api-key/{apiKeyId}

Request Parameters

apiKeyId [UUID] Required: The unique Id of the API Key to update.

Request Body

apiKey.ipAccessControlListId [UUID] Optional Available since 1.30.0

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

Note: An Enterprise plan is required to utilize IP ACLs.

apiKey.metaData.attributes.description [String] Optional

Description of the key.

apiKey.permissions.endpoints [Object] Optional

Example API Key request JSON


{
  "apiKey": {
    "ipAccessControlListId": "eae37b0e-950b-4e92-abcc-d0b310326f66",
    "metaData": {
      "attributes": {
        "description": "updating the key"
      }
    },
    "permissions": {
      "endpoints": {
        "/api/application": [
          "DELETE",
          "POST",
          "GET",
          "PUT",
          "PATCH"
        ]
      }
    }
  }
}

Response

The response for this API contains the Key that was updated.

Table 4. 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 are trying to update 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.id [UUID]: The Id of the API key.
apiKey.insertInstant [Long]: The instant when the API key was added to the FusionAuth database.
apiKey.ipAccessControlListId [UUID]: The Id of the IP Access Control List limiting access to this API key.
apiKey.key [String]: The API key value, this is the string value you will use in the Authorization header to authenticate API requests.
apiKey.keyManager [Boolean]: 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.lastUpdateInstant [Long]: The instant when the API key was last updated in the FusionAuth database.
apiKey.metaData.attributes.description [String]: Description of the key.
apiKey.permissions.endpoints [Object]: 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.tenantId [String]: The unique Id of the Tenant. This value is read-only once the key is created.

Example API Key Response JSON


{
  "apiKey": {
    "id": "b016fa93-e8bc-4b79-b39f-5d37966c0178",
    "insertInstant": 1619119404194,
    "ipAccessControlListId": "eae37b0e-950b-4e92-abcc-d0b310326f66",
    "key": "WHYugARKzum-jHvzCk5-C558EKPaYEECz5k8fDZayIaFiZHRKqy9kaQn",
    "keyManager": false,
    "lastUpdateInstant": 1619121061858,
    "metaData": {
      "attributes": {
        "description": "updating the key"
      }
    },
    "permissions": {
      "endpoints": {
        "/api/application": [
          "DELETE",
          "POST",
          "GET",
          "PUT",
          "PATCH"
        ]
      }
    },
    "tenantId": "94f751c5-4883-4684-a817-6b106778edec"
  }
}

Delete an API Key

This API is used to delete a Key. Deletion is possible only with another API key with equal or greater permissions. A tenant-scoped API key can delete another API key for the same tenant.

Delete the API Key with the given Id

URI

DELETE /api/api-key/{apiKeyId}

Request Parameters

apiKeyId [UUID] Required: The unique Id of the API Key to delete.

Response

This API does not return a JSON response body.

Table 5. Response Codes
Code	Description
200	The request was successful. The response will be empty.
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 are trying to delete 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.

API Key APIs

Overview

The Key Manager Setting

Create an API Key

Request Parameters

Request Body

Response

Response Body

Create a New API Key From an Existing API Key

Response

Response Body

Retrieve an API Key

Request Parameters

Response

Response Body

Update an API Key

Request Parameters

Request Body

Response

Response Body

Delete an API Key

Request Parameters

Response

Feedback

How helpful was this page?

See a problem?

Have a question or comment to share?