Creating and configuring authorizations in Management API

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.

Retrieving subscribed authorization types

To retrieve all subscribed authorization types, follow these steps:

  1. Create a GET request to the following endpoint:

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

  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 --request GET 'https://{{INSTANCE}}/api/connection-types/' \
--header 'Authorization: Token {{KEY}}'

The available authorization types listed in the response may differ for each instance.

Searching for an authorization type by name

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

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

  2. Replace the CONNECTION_TYPE_NAME with the authorization name retrieved in the response of the API call described in Retrieving subscribed authorization types.

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

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

Listing all authorizations of an authorization type

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

  1. Create a GET request to the following endpoint:

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

  2. Find the value of parameter id and use it in {{CONNECTION_TYPE}} placeholder. Find the IDs and their values in response to the API call described in Retrieving subscribed authorization types.

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

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

Retrieving required options for an authorization type

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

  1. Create an OPTIONS request to the following endpoint:

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

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

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

  4. Send the request.

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

Creating an authorization

To create an authorization, follow these steps:

  1. Create a POST request to the following endpoint:

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

  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. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. 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}}"
}

  5. 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: Token {{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:

  1. Create a GET request to the following endpoint:

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

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

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

  4. Send the request.

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

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

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:

  1. Create a POST request to the following endpoint:

    https://{{INSTANCE}}/api/connection-invite/

  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. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include the following parameters:

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:

"Hello {{ user }},

Please click on the following links to 
authorize the connections:
								
{{ links }}
								
Best regards,
Adverity Team"

send_invite_email

(Optional) Set this parameter to false to skip sending the authorization email.

  1. 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-invite/' \
--header 'Authorization: Token {{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:

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.

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.

Editing an authorization

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

  1. Create a PATCH request to the following endpoint:

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

  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. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include the parameter and the new value you want to assign to it. For example, {"name": "NEW_NAME"}

  5. 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: Token {{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:

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:

  1. Create a POST request to the following endpoint:

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

  2. Replace the CONNECTION_TYPE_ID with the authorization type ID retrieved in the response of the API call described in Retrieving subscribed authorization types.

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

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

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

Listing authorization permissions

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

  1. Create a GET request to the following endpoint:

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

  2. In the HTTP request header, include the parameter Authorization with value Token REMOVED.

  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 -L -X GET 'https://{{INSTANCE}}.datatap.adverity.com/api/billings/{{CONNECTION_ID}}' \
-H 'Authorization: Token REMOVED'

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:

  1. Create a PATCH request to the following endpoint:

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

  2. In the HTTP request header, include the parameterAuthorization with value Token REMOVED.

  3. In the HTTP request header, include the parameter Content-Type with value application/json.

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

  5. 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: Token REMOVED' \
--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:

  1. Create a PATCH request to the following endpoint:

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

  2. In the HTTP request header, include the parameterAuthorization with value Token REMOVED.

  3. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include theenable_all_billing_objects parameter and set it to true, and include an empty objects list.

  5. 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: Token REMOVED' \
--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:

  1. Create a GET request to the following endpoint:

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

  2. In the HTTP request header, include the parameter Authorization with value Token {{KEY}} and the parameter Accept with value text/csv.

  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 --request GET 'https://{{INSTANCE}}/api/billing-objects/export/' \
--header 'Authorization: Token {{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:

  1. Create a DELETE request to the following endpoint:

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

  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.

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

Updating authorization tokens

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

  1. Create a PATCH request to the following endpoint:

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

  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. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. 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: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"access_token": "ACCESS_TOKEN",
	"refresh_token": "REFRESH_TOKEN",
	"expires": "EXPIRATION_DATE"
}'