> 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 Spark allows users to manage the API keys used authenticate calls to Spark APIs. ## API key terminology {% hint style="info" %} The previous concept of API key groups containing API key instances has been simplified. All API keys are now listed in the user interface without any group hierarchy. API key group names are now associated to API key names. {% endhint %} By default an API key will be able to call the following APIs: * [Batch APIs](/spark-apis/batch-apis.md) * [Execute API](/spark-apis/execute-api.md) * [Metadata API](/spark-apis/metadata-api.md) * [Transforms API](/spark-apis/transforms-api.md) * [Validation API](/spark-apis/validation-api.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()` | | Deactivated | Deactivated by user intervention. | A yellow API key expiry warning indicator will be shown based on the following logic. | Key duration | Warning start | | ------------ | ----------------------------------------------------- | | ≤1 days | The warning will always appear. | | ≤5 days | From the 2nd valid date of the key until key expiry. | | ≤7 days | From the 5th valid date of the key until key expiry. | | ≤31 days | From the 24th valid date of the key until key expiry. | ## Make a new API key 1. Click the **New API key** button. 2. Add 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 [Manage users](/tenant-administration/manage-users.md#user-groups) 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`. * Including `tenant-admin` into a key group is only needed if the aim is to use the API key to orchestrate tasks that would be performed by a `tenant-admin`. * For a [Private tenant](/tenant-administration/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. 5. The API key generation method has 2 options: * *Generate for me* where Spark will generate a random API key. * *I will supply my own key* where the user can enter their own key. 6. Click **Create**. 7. The API key will be displayed. The modal cannot be closed unless the API key has been copied. ## Deactivate API key To prevent an API key from being used it can be changed to a *Deactivated* status. 1. From the Action menu choose the "three-dot menu" and select **Deactivate API key**. 2. Review the details and click **Confirm**. ## Update API key This can be used to change the properties of an API key. This will also update a *Deactivated* key to *Active* if the *Active from* date is set to the future. 1. From the Action menu choose the "three-dot menu" and select **Update API key**. 2. Edit the property that you want to change. 3. Click **Update**. ## Rotate API key Update your integration with a new API key without having to redefine all of the details. This will create another API key with the same name and description with advanced *Active from* and *Active until* dates. 1. From the Action menu choose the "three-dot menu" and select **Rotate API key**. 2. Review the properties and the proposed *Active from* and *Active until* dates. 3. Click **Rotate**. ## Delete API key Remove any API keys that are no longer used to simplify API key management. 1. From the Action menu choose the "three-dot menu" and select **Delete API key**. 2. Type in `DELETE` and click the **DELETE**. ## Use an API key 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 {% hint style="info" %} Enhancements are planned to the API key management and this API may replaced in the near future. {% endhint %} 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, 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`
Sample API keys ```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" }, ... ] } } ```
## 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 which other APIs the `x-synthetic-key` can access.