Update an API Key API

Edit on GitHubView Markdown
On this page

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

Request#

API Key Authentication
Update the Key with the given Id
PUT/api/api-key/{apiKeyId}
OpenAPI Spec

Path Parameters#

apiKeyId
  • Type: UUID
  • Required

The unique Id of the API Key to update.

Request Body#

apiKey.expirationInstant
  • Type: Long
  • Optional
  • Available 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.

Note that omitting this field or providing a null value will clear the expiration instant of this API key.

apiKey.key
  • Type: 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
  • Type: UUID
  • Optional
  • Available since 1.30.0

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

Enterprise plan To use , you'll need an Enterprise plan.

apiKey.metaData.attributes.description
  • Type: String
  • Optional

Description of the key.

apiKey.name
  • Type: String
  • Optional
  • Available since 1.56.0

The name of the API key. Must be unique.

If apiKey.retrievable is false then this field is required.

apiKey.permissions.endpoints
  • Type: 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.retrievable
  • Type: Boolean
  • Optional
  • Defaults to true
  • Available 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.

This value is read-only once the key is created. If this value is set to false then the apiKey.name field is required.

apiKey.tenantId
  • Type: 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.

Tenant-scoped keys have read-only access to entities that are shared between tenants. You can further limit these API keys by specifying required endpoints, permissions, and a tenant.

Use care when scoping an API key to the Default tenant. These API keys can make changes to User Registrations for the FusionAuth Admin application via the User Registration API to broaden the effective scope of a key to other tenants.

Example API Key request JSON
{
  "apiKey": {
    "expirationInstant": 1878422400000,
    "ipAccessControlListId": "eae37b0e-950b-4e92-abcc-d0b310326f66",
    "metaData": {
      "attributes": {
        "description": "updating the key"
      }
    },
    "name": "Another Awesome API Key",
    "permissions": {
      "endpoints": {
        "/api/application": [
          "DELETE",
          "POST",
          "GET",
          "PUT",
          "PATCH"
        ]
      }
    }
  }
}

Response#

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

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
404The object you are trying to update doesn't exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

apiKey.expirationInstant
  • Type: Long
  • Available 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.id
  • Type: UUID

The Id of the API key.

apiKey.id
  • Type: UUID

The Id of the API key.

apiKey.insertInstant
  • Type: Long

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

apiKey.ipAccessControlListId
  • Type: UUID
  • Available since 1.30.0

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

apiKey.key
  • Type: String

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 will be the only time the key is returned in the response.

apiKey.key
  • Type: String

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.keyManager
  • Type: 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
  • Type: Long

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

apiKey.metaData.attributes.description
  • Type: String

Description of the key.

apiKey.name
  • Type: String
  • Available since 1.56.0

The name of the API key.

apiKey.permissions.endpoints
  • Type: 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.retrievable
  • Type: Boolean
  • Available since 1.56.0

Indicates whether this key is retrievable.

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

apiKey.tenantId
  • Type: String

The unique Id of the Tenant. This value is read-only once the key is created.

Example API Key Response JSON
{
  "apiKey": {
    "expirationInstant": 1878422400000,
    "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"
      }
    },
    "name": "Another Awesome API Key",
    "permissions": {
      "endpoints": {
        "/api/application": [
          "DELETE",
          "POST",
          "GET",
          "PUT",
          "PATCH"
        ]
      }
    },
    "retrievable": true,
    "tenantId": "94f751c5-4883-4684-a817-6b106778edec"
  }
}

Related

APIs

Create an API Key API

API documentation for the FusionAuth Create an API Key API.

api key managementfusionauth apirest api
APIs

Delete an API Key API

API documentation for the FusionAuth Delete an API Key API.

api key managementfusionauth apirest api
APIs

API Keys API

Learn about the APIs for creating, retrieving, updating and deleting API Keys.

api key managementkey managerfusionauth api
APIs

Retrieve an API Key API

API documentation for the FusionAuth Retrieve an API Key API.

api key managementfusionauth apirest api