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

• Execute API

• Metadata API

• Transforms API

• Validation API

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

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.

Once an API key group is created, it cannot be edited or deleted!

An API key is only displayed once! Please save the key in a secure location!

1. Click on New API key group from the top right corner.

2. Enter the required information.

3. The choice of 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, 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 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 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

An API key is only displayed once! Please save the key in a secure location!

1. Follow View API key instances 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 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 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 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

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

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

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": "[email protected]",
                "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": "[email protected]",
                "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.