Authorizing Management API¶

This article documents how to create and manage Connect API keys for Management API.

See GET /api/v1/auth/keys/introspect/ and POST /api/v1/auth/keys/current/rotate/ in the API reference.

Introduction¶

When using the Management API, you authorize your requests with a Connect API key. You create the key in Adverity, and then send it in the Authorization header of every request.

For the operations available to a key, see the API reference. For more information, see Getting started with the Management API.

This article covers the following tasks:

Creating a Connect API key
Sending a Connect API key in requests
Checking the status of a Connect API key

Creating a Connect API key in Adverity¶

You can create and manage Connect API keys in the Adverity user interface. Each key is assigned to a workspace and gives access only to this workspace and its child workspaces. A key can only do what the permissions you select when you create it allow. If a request needs a permission that the key does not have, Management API rejects the request.

Connect API keys have the following limitations:

By default, Connect API keys can only be generated by a user with Administrator permissions in the root workspace. For more information, see Managing user permissions.

Note

If self-service Management API key management is enabled for your workspace, any authenticated user with workspace access can also generate and manage keys, without Administrator permissions. This applies only to the keys the user generates themselves — such a user can view, list, and revoke only their own keys, not keys generated by other users. Keys they generate must also have an expiry date, of no more than 365 days from creation; only Administrators can generate keys that do not expire or that are exempt from this limit. Administrators retain full access to all keys regardless of this setting. To enable self-service key management for your workspace, contact your Adverity representative.
You can generate up to 25 non-expiring keys per workspace. This limit applies only to keys without an expiry date, which only Administrators can create.
Under self-service key management, each user can additionally generate up to 10 keys with an expiry date for their own use. This limit is per user, not per workspace, and is separate from the 25-key limit on non-expiring keys.
Connect API keys can have an expiry date. Administrators in the root workspace can also generate keys that do not expire, and this is their default. Other users must set an expiry date of no more than 365 days. For more information, see Expiry of a Connect API key.

Opening the Connect API keys page¶

You can open the Connect API keys page in two ways:

From your user menu. Click your user menu, and then click Connect API Keys.

This entry is available only if you can view Connect API keys.
From the Administration page. Go to the Administration page, and then, in the secondary menu, click Management API Keys.

Creating a Connect API key¶

To create a Connect API key, follow these steps:

Open the Connect API keys page. For more information, see Opening the Connect API keys page.
In the top right corner, click Create key.
In the Name field, enter a name for this key, so you can identify it later.
In Select workspace, select the workspace to which this key will be assigned.

You will be able to use this key to access the selected workspace and all its child workspaces.
In Expiration, select when the key expires: in 30, 60, or 90 days, in 1 year, or No expiration. No expiration is only available to Administrators in the root workspace.
In Permissions, set each permission for this API key to No access, Read-only, or Write:

Note

You can only grant scopes that match your own effective permissions. Options you do not have access to are disabled in this dialog. If you request a scope you do not have through Management API directly, the request is rejected.

Workspace
Select Write to assign this API key permissions equivalent to the Datastream Manager user group. This also allows the key to create and update workspaces through Management API. Deleting a workspace is not covered by this scope — the user the key belongs to must have Administrator permissions in the root workspace.

Select Read-only to assign this API key permissions equivalent to the Viewer user group. This also allows the key to list value tables through Management API. For more information, see Configuring mapping tables in Management API.

For more information, see User permissions associated with each group.

Authorization
Select Read-only to read which accounts an authorization is permitted to collect from, and to discover available accounts, profiles, and campaigns.

Select Write to update the set of accounts an authorization is permitted to collect from.

Note

The Authorization permission is independent of the Workspace permission. Selecting Workspace: Write does not grant access to authorization endpoints — you must select Authorization: Read-only or Authorization: Write explicitly.

Datastream
Select Read-only to list datastreams and retrieve their configuration through Management API. This also allows the key to retrieve data extracts and tracked columns. For more information, see Collecting data in Management API and Configuring Data Mapping in Management API.

Select Write to update datastream configuration, including smart schedule settings and tracked columns, through Management API. For more information, see Managing pulling mode and smart schedule in Management API.

Both levels also cover datastream tags: Read-only to list tags and filter datastreams by tag, Write to create, rename, and delete tags and add them to datastreams. For more information, see Tagging datastreams in Management API.

Monitor
Select Read-only to discover custom monitors available for assignment through Management API, and to list Data Quality issues and view issue analytics.

Select Write to assign or unassign custom monitors through Management API, to acknowledge, reopen, and mark Data Quality issues as expected, and to accept a changed column structure into the baseline.

To preview custom monitor rules on a data extract, a key needs Monitor: Read-only and Datastream: Read-only together. For more information, see Bulk assigning custom monitors in Management API and Managing Data Quality issues in Management API.

Transformation
Select Read-only to list and retrieve transformations through Management API.

Select Write to create, edit, and delete transformations through Management API.

Destination
This permission can be assigned only on the root workspace level.

Select Write to create, update and delete destinations through Management API.

User
This permission can be assigned only on the root workspace level.

Configure these permissions to have access to user management endpoints in Management API. User management endpoints are available only when using a Connect API key.

Select Write to also create, update, and delete notification subscriptions through Management API. Subscriptions created this way are owned by the user who issued the key. For more information, see Configuring notifications in Management API.

Usage
Select Read-only to retrieve row-usage and billing metrics through Management API.

Warehouse
Select Read-only to run read-only queries against the workspace’s warehouse and retrieve its schema through Management API. There is no Write option for this permission. For more information, see Querying warehouse data in Management API.
Click Create API key.
Click Copy to copy the generated key.

Warning

The generated key is only displayed once. You will not be able to copy the key again after closing this pop-up window.
Click Close.

As a result, you have created and copied a Connect API key and assigned it to the selected workspace.

Revoking a Connect API key¶

To revoke a Connect API key, follow these steps:

Open the Connect API keys page. For more information, see Opening the Connect API keys page.
Find the key which you want to revoke.
Click Select an action in the key’s row.
Click Revoke.
In the confirmation dialog, enter the key name.
Click Delete API key.

As a result, the key is permanently deleted.

Refreshing a Connect API key¶

To refresh a Connect API key, follow these steps:

Create a POST request to the following endpoint:

https://{{INSTANCE}}/api/v1/auth/keys/current/rotate/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request POST 'https://{{INSTANCE}}/api/v1/auth/keys/current/rotate/' \
--header 'Authorization: Bearer {{KEY}}'

Example of JSON response:

{
    "api_key": "{{NEW_KEY}}"
}

As a result, the key has a new value, returned in the api_key field. Use the new value in all further requests. The old value stops working immediately.

Refreshing changes only the value of the key. The key keeps its name, workspace, permissions, and expiry date. Refreshing does not extend the expiry date.

Expiry of a Connect API key¶

When you create a key, you select when it expires: in 30, 60, or 90 days, in 1 year, or never. Only Administrators in the root workspace can generate keys that never expire.

After its expiry date, a key stops working: every request that uses it is rejected, on both the legacy endpoints (/api/) and the v1 endpoints (/api/v1/). You cannot extend the expiry date of a key, and refreshing a key keeps its expiry date. To keep your integration working, generate a new key before the old one expires and switch your integration to it.

To see when a key expires, open the Connect API keys page, or check the expires_at field returned by the key introspection endpoint. For more information, see Checking the status of a Connect API key.

Sending a Connect API key in requests¶

To authorize a request to Management API, include the Connect API key in the Authorization header with the Bearer scheme. The key works with both the legacy endpoints (/api/) and the v1 endpoints (/api/v1/).

To send a Connect API key, follow these steps:

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/v1/auth/keys/introspect/' \
--header 'Authorization: Bearer {{KEY}}'

As a result, Management API authorizes the request with the permissions of the key, in the workspace the key is assigned to.

Important

A Connect API key is limited to one workspace and its child workspaces, and to the permissions you selected when you created it. Check which permissions your requests need before you create the key.

Checking the status of a Connect API key¶

You can check whether a Connect API key is still active and inspect its scopes with the key introspection endpoint. This is useful for verifying that a key has not been revoked or rotated before you rely on it.

To introspect a Connect API key, follow these steps:

Create a GET request to the following endpoint:

https://{{INSTANCE}}/api/v1/auth/keys/introspect/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/v1/auth/keys/introspect/' \
--header 'Authorization: Bearer {{KEY}}'

Example of JSON response for an active key:

{
    "active": true,
    "scopes": ["workspace:read", "authorization:read"],
    "workspace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "user_id": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "expires_at": null
}

The active field indicates whether the key is valid. The scopes field lists the key’s permissions, and workspace_id identifies the workspace the key is assigned to. The expires_at field holds the date and time the key expires, or null if the key does not expire.

If the key has been revoked, rotated, or is otherwise invalid, the response contains only the active field:

{
    "active": false
}

As a result, you can confirm whether a Connect API key is still valid before you use it.

Note

This endpoint is rate limited by IP address. If you exceed the limit, the endpoint returns a 429 Too Many Requests response.