> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/spark-apis/authorization-api-keys.md).

# Authorization - API keys

{% hint style="warning" %}
Although API keys can be used for machine-to-machine integrations, [Client credentials](/identity-and-access-management/client-credentials.md) are a more secure form of authorization. See [Benefits of client credentials versus API keys](/identity-and-access-management/client-credentials/benefits-of-client-credentials-versus-api-keys.md).
{% endhint %}

`tenant-admin`s can create API keys for integration authorization. An API key is a type of secret shared between a provider and consumer, used through a secure and predefined mechanism for authentication or access.

## API key terminology

By default, an API key can be used to authorize calls to following APIs:

* [Batch APIs](/spark-apis/batch-apis.md)
* [Execute API](/spark-apis/execute-api.md)
* [Metadata APIs](/spark-apis/metadata-api.md)
* [Transforms APIs](/spark-apis/transforms-api.md)
* [Validation APIs](/spark-apis/validation-apis.md)

See [Permissions - Features permissions](/spark-apis/authorization-api-keys/permissions-features-permissions.md) to allow API keys to access additional APIs.

## View API keys

By default, **Active** keys will be displayed sorted by the earliest key to expire. Filter the list of API keys using the icons in the heading row.

| Status               | Description                                  |
| -------------------- | -------------------------------------------- |
| Active               | `Active from` `<` `NOW()` `<` `Active until` |
| Active in the future | `NOW()` `<` `Active from`                    |
| Expired              | `Active until` `<` `NOW()`                   |
| Revoked              | Deactivated by user intervention.            |

A yellow API key expiry warning indicator will be shown based on the following logic.

| Key duration | Warning start                                         |
| ------------ | ----------------------------------------------------- |
| `≤1 d`       | The warning will always appear.                       |
| `≤5 d`       | From the 2nd valid date of the key until key expiry.  |
| `≤7 d`       | From the 5th valid date of the key until key expiry.  |
| `≤31 d`      | From the 24th valid date of the key until key expiry. |

## Add a new API key

1. Select the **New API key** button.
2. Enter a name for the API key and an optional **Description**.
3. Define the **Active from** and **Active until** dates for the API key. This determines the valid period for this API key.
4. The choice of [User groups](/identity-and-access-management/user-groups.md) is important. If multiple user groups are selected, the API key generated from this API key group will have the greatest of the permissions across the API key groups.
   * For a shared tenant, where users have access to all folders and services within a tenant:
     * Only `1` API key group should be necessary, one that includes only `user:pf`.
   * For a [Private tenant](/identity-and-access-management/private-tenant.md), where users have restricted access to folders and services:
     * Multiple key groups can be assigned, however:
       * API keys will include permissions from the assigned user groups.
       * For any overlapping permissions, the greater permissions will apply.
     * It is not recommended to include `supervisor:pf` or `tenant-admin` user groups into an API key.
5. The API key generation method has 2 options:
   * **Generate for me** where Spark will generate a random API key. This could be useful to coordinate access across multiple environments.
   * **I will supply my own key** where the user can enter their own key.
6. Select **Create**.
7. The API key will be displayed. The modal cannot be closed unless the API key has been copied.

## API key action

Additional actions can be performed on an API key from the ellipsis menu.

### Deactivate API key

An API key can be deactivated such that it cannot be used. The status of the key will be changed to **Revoked**.

### Update API key

This can be used to change the properties of an API key. If you update a **Deactivated** key such that the current date and time is within the **Active from** and **Active until** dates, the key will update to **Active.**

### Rotate API key

Update your integration with a new API key without having to re-enter all of the details. This creates another key with the same **Name** and **Description** and advances the **Active from** and **Active until** dates.

### Delete API key

Before an API key is deleted, Spark will request confirmation for the delete action. After confirmation, the key will be deleted. There is no process to recover deleted keys.

## Use an API key for integration

For APIs that accept API keys, the request header must include:

* `x-synthetic-key` for the API key.
* `x-tenant-name` for the tenant name.

## List API keys with an API call

Get a list of API keys.

Returns: List of API keys including name, description, user groups, active and expiry dates.

With this information, the data can be used to extract expiration metadata, evaluate lifetime thresholds, and trigger internal notifications.

### Sample request

```shellscript
curl --location 'https://utilities.myenvironment.coherent.global/mytenant/api/v1/key/apikeys?_page=1&_size=100&type=synthetic&status=active' \
--header 'Authorization: Bearer {token}'
```

### Sample response

`HTTP 200 OK` `Content-Type: application/json`

<details>

<summary>Sample API keys</summary>

```json
{
    "status": "success",
    "data": {
        "count": 72,
        "page": 1,
        "pageSize": 100,
        "result": [
            {
                "id": "bc20b868-d001-408f-aa74-76561eb79dc1",
                "userId": "05ba7514-4a5d-4308-b624-c79605cfca7e",
                "name": "key1",
                "description": "key1",
                "masked": "4f5******************************801",
                "status": "Active",
                "type": "Synthetic",
                "groups": [
                    "tenant-admin",
                    "user:pf"
                ],
                "createdAt": "2022-09-28T07:46:53.248723Z",
                "createdBy": "dinesh.kadachha@coherent.global",
                "updatedAt": "2022-09-28T07:47:58.854069Z",
                "activeFrom": "2022-09-28T07:46:43Z",
                "expireAt": "2099-11-30T07:46:52Z",
                "lastUsedAt": "2022-09-28T07:47:58.805336Z"
            },
            {
                "id": "3855813e-d373-4c81-9756-27fd3a6dd5d0",
                "userId": "2b88de7f-53ba-4f36-86ad-0341802ff098",
                "name": "QA",
                "description": "QA",
                "masked": "256******************************415",
                "status": "Active",
                "type": "Synthetic",
                "groups": [
                    "user:pf"
                ],
                "createdAt": "2022-09-28T07:44:15.408539Z",
                "createdBy": "dinesh.kadachha@coherent.global",
                "updatedAt": "2022-09-28T07:45:28.17975Z",
                "activeFrom": "2022-09-28T07:44:05Z",
                "expireAt": "2099-11-30T07:44:14Z",
                "lastUsedAt": "2022-09-28T07:45:28.1288282Z"
            },
            ...
        ]
    }
}
```

</details>

## Review the features permissions for synthetic keys

We strongly recommend reviewing the [Permissions - Features permissions](/spark-apis/authorization-api-keys/permissions-features-permissions.md) to understand how to authenticate to other APIs.