Creating and configuring authorizations in Management API

On this page

This guide explains how to search for available authorization types and authorizations, how to create, set up and configure authorizations with the Management API, as well as how to list and configure authorization permissions.

Prerequisites

Before you complete the procedures in this guide, perform the following action:

Use a Connect API key with the following permissions:
- Authorization: Read-only (authorization:read) to list authorization types and authorizations, to start an authorization, and to view or export billing objects.
- Authorization: Write (authorization:write) to create, update, or delete authorizations, to send authorization invites, and to update tokens and billing objects.
Picking Write for a permission also gives the key its Read-only access. Without the permission a request needs, Management API returns HTTP 403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity.

Retrieving subscribed authorization types

To retrieve all subscribed authorization types, follow these steps:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/connection-types/
```
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 --request GET 'https://{{INSTANCE}}/api/connection-types/' \
--header 'Authorization: Bearer {{KEY}}'

Searching for an authorization type by name

Optionally, to search for an authorization types by their name, follow these steps:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/connection-types/?search=CONNECTION_TYPE_NAME
```
Note: Search is included as a URL parameter.
Replace the CONNECTION_TYPE_NAME with the authorization name retrieved in the response of the API call described in Retrieving subscribed authorization types.
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 --request GET 'https://{{INSTANCE}}/api/connection-types/?search=CONNECTION_TYPE_NAME' \
--header 'Authorization: Bearer {{KEY}}'

Listing all authorizations of an authorization type

To list all authorizations of a specific authorization type, follow these steps:

Create a GET request to the following endpoint:

https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/

In the endpoint, replace {{CONNECTION_TYPE}} with the id of the authorization type for which you want to list all authorizations. To find the id, see Retrieving subscribed authorization types
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 --request GET 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/' \
--header 'Authorization: Bearer {{KEY}}'

The response includes the following fields for each authorization:

credentials_validated — Boolean. true if the credentials for this authorization were successfully validated during setup or the last explicit check.
is_authorized — String. "granted" if the authorization is currently active and valid; "not_granted" otherwise. For OAuth 2.0 authorizations, this also verifies that a valid access token exists. For non-OAuth 2.0 authorizations, this value mirrors credentials_validated.

Retrieving required options for an authorization type

To retrieve options required to create an authorization of a certain type, follow these steps:

Create an OPTIONS request to the following endpoint:

https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections

Find the value of parameter id and use it in the {{CONNECTION_TYPE}} placeholder. Find the IDs and their values in the response to the API call described in Retrieving subscribed authorization types.
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.
In the response, search for the JSON objects marked as "required": true. Use these required objects in the next section, Creating an authorization.

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

curl --location --request OPTIONS 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/' \
--header 'Authorization: Bearer {{KEY}}'

Creating an authorization

To create an authorization, follow these steps:

Create a POST request to the following endpoint:

https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the objects marked as "required": true in the response of the API call described in Retrieving required options for an authorization type. See the example of the request body below for more information:
```
{
    "name": "NEW_CONNECTION",
    "stack": {{STACK_ID}},
    "username": "USERNAME",
    "password":"PASSWORD"
}
```
For some authorization types, other options may be required. In the following example of the request body, the app option is included.
```
{
    "name": "NEW_CONNECTION",
    "stack": {{STACK_ID}},
    "app": "{{APP_ID}}"
}
```
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 --request POST 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/' \
 --header 'Authorization: Bearer {{KEY}}' \
 --header 'Content-Type: application/json' \
 --data-raw '{
     "name": "NEW_CONNECTION",
     "stack": {{STACK_ID}},
     "username": "USERNAME",
     "password":"PASSWORD",
     "app": {{APP_ID}}
 }'

Authorizing an OAuth 2.0 authorization

To authorize an authorization that uses OAuth 2.0 protocol, follow these steps:

Create a GET request to the following endpoint:

https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/authorize/

For the parameter CONNECTION_TYPE, use the value of the parameter id in the response of the API call described in Retrieving subscribed authorization types.
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.
From the API response, use the URL (the parameter is marked as url) to redirect you to the login page of the data provider for your authorization. See the response example below:
```
{
    "status": "ok",
    "is_authorized": false,
    "is_oauth": true,
    "url": "https://INSTANCE/oauth2/token/TOKEN_VALUE"
}
```
At the data provider website, use your credentials to authorize your authorization.

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

curl --location --request GET 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/authorize/' \
--header 'Authorization: Bearer {{KEY}}'

Redirecting after authorization

To redirect the user to a specific URL after they complete the OAuth 2.0 flow, append the return_url query parameter to the authorize endpoint:

https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/authorize/?return_url={{RETURN_URL}}

Replace {{RETURN_URL}} with the URL to redirect to after authorization completes. When return_url is set, the platform redirects the user to this URL instead of the default Adverity page.

This is particularly useful in the connection invite flow: when you share an authorization link with an external user, embedding a return_url lets you detect when they complete the authorization, for example by pointing to a webhook or tracking endpoint.

Creating an authorization and authorizing it

Use this request to create an authorization and generate a link to authorize it in Adverity.

If you do not have the required credentials for the data source or destination you want to authorize Adverity to access, you can send an email asking someone else to authorize the connection for you.

To create an authorization and generate a link to authorize it in Adverity, follow these steps:

Create a POST request to the following endpoint:
```
https://{{INSTANCE}}/api/connection-invite/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the parameters from the table below.
Send the request.

Scroll horizontally to see the full table.

Parameter name	Description
content_types	Enter a list of dictionaries containing `content_type` and `name` parameters for each authorization you want to create and authorize.
…/content_type	Enter the ID of the authorization type for the new authorization.
…/name	Enter a descriptive name for the authorization.
email	Enter the email of the person who needs to authorize the access.
notification_emails	Enter the emails that will be notified once the access is granted or in case of any future issues with the authorization.
stack	Enter the stack (workspace) ID.
email_body	(Optional) Enter the email body if you want to customize it. The email body must contain `{{ user }}` and `{{ link }}` placeholders. If this parameter is not used, the following body will be used:
send_invite_email	(Optional) Set this parameter to `false` to skip sending the authorization email.

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/connection-invite/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "content_types": [
        {
            "content_type": "{{CONNECTION_TYPE_ID}}",
            "name": "{{CONNECTION_NAME}}"
        }
    ],
    "email": "recipient_email@organization.com",
    "notification_emails": ["email1@organization.com", "email2@organization.com"],
    "stack": {{STACK_ID}}
}'

Response

The response contains the following parameters for each created authorization:

Scroll horizontally to see the full table.

Response parameter	Description
link	Authentication link for the authorization. Open this link to authorize the created authorization. The same link is included in the email body sent to the email address provided in the request body.
name	Name of the authorization provided in the request body.
content_type_id	Authorization type ID provided in the request body.
connection_invite_uuid	Unique identifier of the connection invite. Use this value to identify which authorization was created from this invite request. For more information, see Identifying the authorization created from a connection invite.

The person from whom you are requesting access will receive an email and can authorize the connection using Adverity user interface. For more information, see Responding to an authorization request.

Identifying the authorization created from a connection invite

When the external grantor authorizes access, the resulting authorization includes a connection_invite_uuid field that matches the field returned in the connection invite response. Use this to correlate a specific invite with the authorization it produced.

To identify the authorization created from a specific connection invite, follow these steps:

Note the connection_invite_uuid value from the connection invite response.
Create a GET request to the following endpoint to list authorizations of the relevant type:
```
https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.
In the response, find the authorization where the connection_invite_uuid field matches the value from the invite response.

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

curl --location --request GET 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/' \
--header 'Authorization: Bearer {{KEY}}'

Retrieving a specific authorization

To retrieve the details of a specific authorization, follow these steps:

Create a GET request to the following endpoint:

https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/

Replace {{CONNECTION_TYPE}} with the authorization type ID and {{CONNECTION_ID}} with the authorization ID. To find these values, see Listing all authorizations of an authorization type.
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.

As a result, you obtain the details of the specified authorization. The response contains the same fields as the list response, including connector-specific fields for that authorization type.

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

curl --location --request GET 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/' \
--header 'Authorization: Bearer {{KEY}}'

Editing an authorization

The example in this section documents how to change the authorization name. To edit an existing authorization configuration, follow these steps:

Create a PATCH request to the following endpoint:

https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the parameter and the new value you want to assign to it. For example, {"name": "NEW_NAME"}
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 --request PATCH 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"name": "NEW_NAME"}'

Listing and editing authorization permissions

This section of the guide outlines how to perform the following actions:

Starting a metadata update
Listing permissions
Enabling access to individual permissions
Enabling access to all permissions
Exporting a list of available permissions

Most authorizations give Adverity access to multiple items that are linked to the authorization, such as accounts or profiles. When you create an authorization, you set permissions that define which items Adverity can access.

Starting a metadata update

To start a metadata update and ensure that the list of items you can give Adverity permissions to access is up to date, follow these steps:

Create a POST request to the following endpoint:

https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE_ID}}/connections/{{CONNECTION_ID}}/update/

Replace the CONNECTION_TYPE_ID with the authorization type ID retrieved in the response of the API call described in Retrieving subscribed authorization types.
Replace the CONNECTION_ID with the authorization ID retrieved in the response of the API call described in Retrieving required options for an authorization type. In this response, the CONNECTION_ID is displayed as the value of the parameter id.
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 --request POST 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE_ID}}/connections/{{CONNECTION_ID}}/update/' \
--header 'Authorization: Bearer {{KEY}}'

Listing authorization permissions

To see a list of all the permissions for an authorization, follow these steps:

Create a GET request to the following endpoint:

https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}/

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 --request GET 'https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}/' \
--header 'Authorization: Bearer {{KEY}}'

Giving the authorization permissions to selected items

Giving Adverity access to the selected items disables access to all other items by default.

To enable the selected items and, as a result, disable access to all other items by default, follow these steps:

Create a PATCH request to the following endpoint:

https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include theIDs of the permissions that you want to enable under the objects tag.

To disable all permissions except the selected ones, set the enable_all_billing_objects parameter to false.
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 --request PATCH 'https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "objects":[
      {
         "id": {{ID}},
         "is_enabled": true
      }
   ],
   "enable_all_billing_objects": false
}'

As a result, the authorization item with ID {{ID}} is enabled and access to all other items is disabled by default.

Giving Adverity access to all authorization items

To enable access to all and future items, follow these steps:

Create a PATCH request to the following endpoint:

https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the enable_all_billing_objects parameter and set it to true, and include an empty objects list.
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 --request PATCH 'https://{{INSTANCE}}/api/billings/{{CONNECTION_ID}}/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "objects":[
   ],
   "enable_all_billing_objects": true}'

As a result, access is granted to all and future items by default.

Exporting a list of available authorization items

To export a list of the available authorization items for all workspaces to which you have access, follow these steps:

Create a GET request to the following endpoint:

https://{{INSTANCE}}/api/billing-objects/export/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}} and the parameter Accept with value text/csv.
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 --request GET 'https://{{INSTANCE}}/api/billing-objects/export/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Accept: text/csv'

As a result, you have obtained a list of all available authorization items for all workspaces to which you have access.

Deleting an authorization

To delete an authorization, follow these steps:

Create a DELETE request to the following endpoint:

https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/

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

As a result, the authorization is deleted. In the successful response, you receive an empty JSON body.

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

curl --location --request DELETE 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE}}/connections/{{CONNECTION_ID}}/' \
--header 'Authorization: Bearer {{KEY}}'

Updating authorization tokens

To update an authorization token for data source APIs that use OAuth 2.0, follow these steps:

Create a PATCH request to the following endpoint:

https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE_ID}}/connections/{{CONNECTION_ID}}/token/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
In the HTTP request header, include the parameter Content-Type with value application/json.
In the HTTP request body, include the following parameters:
- access_token - the access token that you want to update.
- refresh_token - the refresh token for the authorization.
- expires - the expiration time for the access token in the DateTime format.

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

curl --location --request PATCH 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE_ID}}/connections/{{CONNECTION_ID}}/token/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN",
    "expires": "EXPIRATION_DATE"
}'