Authorization - API keys

Although API keys can be used for machine-to-machine integrations, Client credentials are a more secure form of authorization. See Benefits of client credentials versus API keys.

tenant-admins 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

• Execute API

• Metadata APIs

• Transforms APIs

• Validation APIs

See Permissions - Features permissions to allow API keys to access additional APIs.

View API keys

By default, Active keys are 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 may be shown depending on the remaining key duration.

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 is important. If multiple user groups are selected, the API key generated from this API key group will have the union 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, 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.

Sample request

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

{
    "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": "[e-mail]",
                "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": "[e-mail]",
                "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 to understand how to authenticate to other APIs.