> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Create an API Key

API documentation for the FusionAuth Create an API Key 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. An API key that is tenant scoped can create another key for the same tenant.

A key with key manager permissions can not be created using this API. Only through admin UI or kickstart can you create such a key.

## Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Create a new Key with a randomly generated Id

POST/api/api-key

OpenAPI Spec

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Create a new Key with the provided unique Id

POST/api/api-key/{keyId}

OpenAPI Spec

### Request Parameters

`apiKeyId`UUIDoptionalDefaults to a generated UUIDImmutable

The unique Id of the API Key to create. If not specified a secure random UUID will be generated.

#### Request Body

`apiKey.expirationInstant`LongoptionalAvailable since 1.55.0

The expiration [instant](https://fusionauth.io/docs/reference/data-types.md#instants) of this API key. Using an expired API key for [API Authentication](https://fusionauth.io/docs/apis/authentication.md) will result in a 401 response code.

`apiKey.key`Stringoptional

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`UUIDoptionalAvailable since 1.30.0

The Id of the [IP Access Control List](https://fusionauth.io/docs/apis/ip-acl.md) limiting access to this API key.

**Note:** To use , you'll need an Enterprise plan.

`apiKey.metaData.attributes.description`Stringoptional

Description of the key.

`apiKey.name`StringoptionalAvailable 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`Objectoptional

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`BooleanoptionalDefaults to trueAvailable 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`Stringoptional

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.

*Example API Key request JSON*

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

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Create a new Key from an existing Key with a randomly generated Id

POST/api/api-key/

OpenAPI Spec

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Create a new Key from an existing Key with the provided unique Id

POST/api/api-key/{keyId}

OpenAPI Spec

### Request Parameters

`apiKeyId`UUIDoptionalDefaults 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

`sourceKeyId`UUIDrequired

The Id of an existing API Key from which a copy will be made. The resulting key will have the same permissions of this existing key.

Note that you cannot copy a key designated as a key manager.

`apiKey.name`StringoptionalAvailable since 1.56.0

The name of the API key. Must be unique.

If the **retrievable** value of the source key is `false` then this field is required.

*Example API Key request JSON*

```json
{
  "sourceKeyId": "de36ce0f-70db-4d73-b0b2-9f82c1572761",
  "apiKey": {
    "name": "Awesome API Key - copy"
  }
}
```

## Response

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

*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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). |
| 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.expirationInstant`LongAvailable since 1.55.0

The expiration [instant](https://fusionauth.io/docs/reference/data-types.md#instants) of this API key. Using an expired API key for [API Authentication](https://fusionauth.io/docs/apis/authentication.md) will result in a 401 response code.

`apiKey.id`UUID

The Id of the API key.

`apiKey.id`UUID

The Id of the API key.

`apiKey.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the API key was added to the FusionAuth database.

`apiKey.ipAccessControlListId`UUIDAvailable since 1.30.0

The Id of the [IP Access Control List](https://fusionauth.io/docs/apis/ip-acl.md) 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](https://fusionauth.io/docs/apis/authentication.md) requests.

If the **apiKey.retrievable** value is `false` then this will be the **only** time the key is returned in the response.

`apiKey.key`String

The API key value. This is the string value you will use in the Authorization header to [authenticate API](https://fusionauth.io/docs/apis/authentication.md) requests.

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

`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](https://fusionauth.io/docs/reference/data-types.md#instants) when the API key was last updated in the FusionAuth database.

`apiKey.metaData.attributes.description`String

Description of the key.

`apiKey.name`StringAvailable since 1.56.0

The name of the API 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.retrievable`BooleanAvailable 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`String

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

*Example API Key Response JSON*

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