Authorizing Management API

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:

For more information on how to refresh an API key, see Refreshing the Management API key.

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

  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 image2 Select an action in the key’s row.

  5. Click image3 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 parameter Authorization 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}}'
Contents