Authorizing Management API

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

Introduction

When using the Management API, you need to authorize your requests with a key.

You can generate a Management API key in two ways:

• Generating an API key through Management API

• Generating an API key in Adverity

For more information on how to refresh an API key, see Refreshing a Management API key generated in UI.

Generating an API key through Management API

To obtain an API key for the Adverity Management API, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/auth/token/

2. In the HTTP request header, include the parameter Content-Type with value application/x-www-form-urlencoded.

3. In the HTTP request body, include the username and password parameters, and then include your respective values for these parameters.

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

curl --location --request POST 'https://{{INSTANCE}}/api/auth/token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw '{
	"username"="{{USERNAME}}",
	"password"="{{PASSWORD}}"
}'

Example of JSON response:

{
    "username": "your.username@example.com",
    "token": "123",
    "expires_in": null
}

As a result, an API key for Management API has been generated and returned in the response in the token field.

When sending requests to Management API, include this API key in the request header in the following way:

--header 'Authorization: Token {{KEY}}'

Generating an API key in Adverity

You can generate and manage Management API keys in the Administration page in Adverity. These keys are assigned to a workspace and give access only to this workspace and its child workspaces.

Management API keys generated in the Administration page have the following limitations:

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

• You can generate up to 5 keys per workspace.

• API keys generated in the Administration page do not expire.

Generating a Management API key

To create a Management API key, follow these steps:

1. Go to the Administration page.

2. In the secondary menu, click Management API keys.

3. In the top right corner, click Create key.

4. In the Name field, enter a name for this key, so you can identify it later.

5. 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.

6. In Permissions, set permissions for this API key with the following options:

   • workspace
     Select write to assign this API key permissions equivalent to the Datastream Manager user group.
     Select read to assign this API key permissions equivalent to the Viewer user group.
     For more information, see User permissions associated with each group.

   • 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 an API key generated in the user interface.

7. Click Create API key.

8. Click Copy to copy the generated key.

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

9. Click Close.

As a result, you have generated and copied an API key for Management API and assigned the key to the selected workspace.

When sending requests to Management API, include this API key in the request header in the following way:

--header 'Authorization: Bearer {{KEY}}'

Revoking a Management API key

To revoke a Management API key, follow these steps:

1. Go to the Administration page.

2. In the secondary menu, click Management API keys.

3. Find the key which you want to revoke.

4. Click Select an action in the key's row.

5. Click Revoke.

6. In the confirmation dialog, enter the key name.

7. Click Delete API key.

As a result, the key is permanently deleted.

Refreshing a Management API key generated in UI

To refresh a Management API key, follow these steps:

1. Create a POST request to the following endpoint:

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

2. In the HTTP request header, include the parameterAuthorization with value Bearer {{KEY}}.

3. 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}}'