# Authorization - API keys
Spark allows users to manage the API keys used authenticate calls to Spark APIs.
## API key terminology
* An API key group can contain multiple API key instances.
* A key instance would correspond to an API key that is used for authentication.
* Multiple key instances are useful for managing key rotation where the "to be" deactivated and next API key have an overlap for continuity.
* An API key group represents the combined access rights of multiple user groups.
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.
## API key groups
API keys on Spark are grouped together for ease of management into an API Key Group. Tenant-admins are the only users who are allowed to view these API keys (in encrypted format). All other users will not be able to see this page.
### View API key groups
1. Login using `tenant-admin` credentials.
2. Choose *Options* from the [Navigation menu](/navigation/navigation-menu.md#user-menu).
3. In the left-hand navigation that appears, select *API keys*.
4. This will show you a list of API key groups on the environment and relevant information.
There are also a few additional features on this page:
* Enter an entire API key into the search filter and press **Enter**. The associated API key group will be filtered.
* API key groups can also be filtered by the user groups they contain.
* Hover on the last used time to see the exact time and date an API was called using the specific key.
* API key groups that have soon-to-be expiring API key instances will have a yellow indicator. The indicator follows the logic described in [#api-key-expiry-warning](#api-key-expiry-warning "mention").
### Add API key groups
There can be many reasons to create a new API key group:
* Create API keys to make API calls to some/all services in Spark
* Different applications or teams require a separate set of API keys. An API key that accesses the minimum number of required Spark services is more secure.
* Using a different set of API keys that require elevated permissions to Spark's, see [Permissions - Features permissions](/spark-apis/authorization-api-keys/permissions-features-permissions.md).
|  |  |
| -------------------------------- | -------------------------------- |
{% hint style="warning" %}
Once an API key group is created, it cannot be edited or deleted!
{% endhint %}
{% hint style="warning" %}
An API key is only displayed once! Please save the key in a secure location!
{% endhint %}
1. Click on **New API key group** from the top right corner.
2. Enter the required information.
3. The choice of [Manage users](/tenant-administration/manage-users.md#user-groups) is important. If multiple user groups are selected, the API key instances 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 instances to orchestrate tasks that would be performed by a `tenant-admin`.
* For a [Private tenant](/tenant-administration/private-tenant.md), where users have 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.
4. When creating an API key group, a first API key instance is also created. Define the active and expiry dates of the API key instance.
5. Click **Confirm** to create the key group.
6. The API key will be displayed. The modal cannot be closed unless the API key has been copied.
## **API key instances**
Multiple API key instances can be generated inside an API key group to allow for key rotation. This can be used to reduce the impact of keys that may be exposed externally. Keys can also be instantly deactivated.
API key instances take the same name, description, and user groups as their parent API key group.
### View API key instances
1. Follow [#view-api-key-groups](#view-api-key-groups "mention") to arrive at the *API keys* screen.
2. Click the API key group of focus.
3. This will show you a list of API key instances and relevant information including the API key status and API key warning.
There are also a few additional features on this page:
1. Enter an entire API key into the search filter and press **Enter**. The API key instance will be displayed with the associated information.
2. API key instances can also be filtered by their status, active dates, or usage.
3. API key groups that have soon-to-be expiring API key instances will have a yellow indicator. See [#api-key-expiry-warning](#api-key-expiry-warning "mention").
#### API key status
| Status | Description |
| -------------------- | -------------------------------------- |
| Active | Keys that can currently be used. |
| Active in the future | Key that will be active in the future. |
| Expired | Key that is past the validity date. |
| Deactivated | Deactivated by user intervention. |
#### API key expiry warning
The yellow API key expiry warning indicator is 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 instance until key expiry. |
| ≤7 days | From the 5th valid date of the key instance until key expiry. |
| ≤31 days | From the 24th valid date of the key instance until key expiry. |
### Add API key instances
| 
|  | 
|
| ------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | |  |
{% hint style="warning" %}
An API key is only displayed once! Please save the key in a secure location!
{% endhint %}
1. Follow [#view-api-key-instances](#view-api-key-instances "mention") to arrive at the API key instance screen.
2. Click *New API key* and choose one of 2 options:
* *Generate API key* where Spark will generate a random API key.
* *Create custom API key* where the user can enter their own key.
3. Specify the active period for the new API key instance.
4. If *Generate API key* was selected:
1. The API key will be displayed. The modal cannot be closed unless the API key has been copied.
5. If *Create custom API key* was selected:
1. The modal will display an input box for to add an API key string. The key MUST be be 20 to 128 characters long and contain only alphanumeric characters or the dash character `-`.
2. Click **Create**.
3. The API key will be displayed again. The modal cannot be closed unless the API key has been copied.
### Change the active period
API key active periods can be extended if a key is about to expire.
1. Follow [#view-api-key-instances](#view-api-key-instances "mention") to arrive at the API key instance screen.
2. Click on the "three-dot menu" and select *Edit active period*.
3. Modify the active dates and click **Confirm**.
4. Spark will indicate if the change has been made.
### Deactivate API key instances
A deactivated API key instance will not be able to call Spark APIs.
1. Follow [#view-api-key-instances](#view-api-key-instances "mention") to arrive at the API key instance screen.
2. Click on the "three-dot menu" and select **Deactivate**.
3. Confirm the change.
4. Spark will indicate if the change has been made.
### Reactivate API key instances
A deactivated or expired key can be reactivated at any time.
1. Follow [#view-api-key-instances](#view-api-key-instances "mention") to arrive at the API key instance screen.
2. Filter for *Expired* or *Deactivated* statuses.
3. Click on the "three-dot menu" and select **Reactivate**.
4. Set the active dates and click **Confirm**.
5. Spark will indicate if the change has been made.
## 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 key instances.
Returns: List of API key instances 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.coherent.global/spark-apis/authorization-api-keys.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.