Authorization - API keys

Spark allows users to manage the API keys used authenticate calls to Spark APIs.

API key terminology

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.

By default an API key will be able to call the following APIs:

• Batch APIs

• Execute API

• Metadata API

• Transforms API

• Validation API

See Permissions - Features permissions 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 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, 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

Enhancements are planned to the API key management and this API may replaced in the near future.

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

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 which other APIs the x-synthetic-key can access.