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 Billing Objects.

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 authorization

To authorize your authorization, 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}}'

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 Billing Objects

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

Billing Objects are entities belonging to an authorization. You can choose which Billing Objects Adverity can access and collect data from. For more information, see the glossary entry for Billing Objects

Starting a metadata update

To start a metadata update and ensure that the list of Billing Objects 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 Billing Objects

To see a list of all the Billing Objects 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'

Enabling access to the selected Billing Objects

Enabling access to the selected Billing Objects disables access to all other Billing Objects by default.

To enable the selected Billing Objects and, as a result, disable access to all other Billing Objects 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 Billing Objects that you want to enable under the objects tag.
    To disable all Billing Objects 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 billing object with ID {{ID}} is enabled and access to all other Billing Objects is disabled by default.

Enabling access to all Billing Objects

To enable access to all and future Billing Objects, 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 Billing Objects by default.

Exporting a list of available Billing Objects

To export a list of the available Billing Objects 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 Billing Objects 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"
}'