Creating and configuring authorizations in Management API

This article documents 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 value Token {{TOKEN}}.

  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 {{TOKEN}}'

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

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_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 value Token {{TOKEN}}.

  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 {{TOKEN}}' \

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 value Token {{TOKEN}}.

  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 {{TOKEN}}'

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 value Token {{TOKEN}}.

  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 {{TOKEN}}'

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 value Token {{TOKEN}}.

  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 {{TOKEN}}' \
--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. Find the value of the CONNECTION_ID in the response of the API call described in the section Retrieving required options for an authorization type. In this response, the CONNECTION_ID is displayed as the value of the parameter id.

  3. In the HTTP request header, include the parameter Authorization with value Token {{TOKEN}}.

  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 {{TOKEN}}'

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 value Token {{TOKEN}}.

  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 {{TOKEN}}' \
--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 GET request to the following endpoint:

    https://{{INSTANCE}}/api/update-metadata-jobs/

  2. In the HTTP request header, include the parameter Authorization with value Token {{TOKEN}}.

  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/update-metadata-jobs/' \
--header 'Authorization: Token {{TOKEN}}'

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

Enabling access to individual Billing Objects disables access to all other Billing Objects by default.

To enable individual 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 parameter Content-Type with value application/json.

  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 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 parameter Content-Type with value application/json.

  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 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 {{TOKEN}} 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 {{TOKEN}}' --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 value Token {{TOKEN}}.

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 {{TOKEN}}'

Updating authorization tokens

This section is related to specific APIs which require OAuth 2.0, specifically Facebook connections.

To update an authorization token, import the following code to your HTTP client and edit the red placeholders:

curl --location --request PATCH 'https://{{INSTANCE}}/api/connection-types/{{CONNECTION_TYPE_ID}}/connections/{{CONNECTION_ID}}/token/' \
--header 'Authorization: Token {{TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw 'access_token=SYSTEM_GENERATED_TOKEN'