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

  4. (Optional) In the HTTP request body, include the expires_in parameter to configure the expiration duration for the API key.

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}}",
	"expires_in":"{{EXPIRATION}}"
}'

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. In the platform navigation menu, click Administration.

  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, select whether this key has Read-only or Write permissions.

  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 this pop-up window closes.

  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. In the platform navigation menu, click Administration.

  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

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 one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  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: Token {{KEY}}'