Creating and viewing authorizations

This guide explains how to create an authorization for a data source or destination, and how to view your existing authorizations.

Introduction

What is an authorization?

An authorization gives Adverity access to a data source or a destination. You need to create an authorization to collect data and load it into external destinations. You can use one authorization to create multiple datastreams and destinations.

What do I need to create an authorization?

To set up an authorization, you need to provide valid credentials, such as a username and password, or an API Key, for example. The credentials required differ for each data source and destination. If you do not have credentials to create an authorization, you can ask someone else to create an authorization for you.

What are authorization 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.

If an authorization does not ask you to select the permissions for items you want to give Adverity access to, this means that the authorization only grants Adverity access to a single item, for example a single account.

Who can use an authorization that I create?

An authorization is available to use in the workspace in which it was created, and any child workspaces belonging to this workspace. This means that all users with access to these workspaces can use the authorization to collect or load data.

Creating an authorization

This video guide explains how to create authorizations in Adverity using your own credentials, and by asking someone else to create the authorization using their credentials.

Using your own credentials to create an authorization

If you have valid credentials for the data source or destination you want to authorize Adverity to access, follow these steps:

1. Go to the Authorizations page.

2. In the top right corner of the page, click + Create authorization.

3. Search for and click the data source or destination for which you want to create an authorization.

4. Click Access using your credentials.

5. Use your credentials to create the authorization:

   • For some authorizations, click Next and then enter the required credentials (for example, a username and password).

   • For some authorizations, you will be taken to a login page where you can enter your credentials to authorize Adverity.

6. If you are creating an authorization for a data source with permissions, choose which permissions Adverity can access using this authorization:

   • Grant access to all items, including those created in the future - Select this option to give Adverity permissions to access all items associated with the credentials you have used. Adverity will also have access to all associated items created in the future.

   • Select specific items to which you want to grant access - Select this option to only give Adverity permissions to access the selected items. You will need to grant Adverity access to any associated items that are created in the future.

7. Click Confirm.

As a result, the authorization is set up and you are taken to the authorization overview page. For more information about updating, deleting and synchronizing authorizations, see Managing authorizations.

Asking someone else to create an authorization

If you do not have the required credentials for the data source or destination you want to authorize Adverity to access, you can ask someone else to create an authorization for you. The person you ask then needs to follow the steps set out in Responding to an authorization request below.

To ask someone else to create an authorization for you, follow these steps:

1. Go to the Authorizations page.

2. In the top right corner of the page, click + Create authorization.

3. Search for and click the connector or destination for which you want to create an authorization.

4. Click Access using someone else's credentials.

5. Click Next.

6. Fill in the following fields:

   Email

   Enter the email address of the person you want to ask to create the authorization.

   Authorizations added

   (Optional) Rename the authorization that you want the recipient to create.

   (Optional) Ask the recipient to create additional authorizations to different data sources or destinations:

   1. Click + Add more authorizations.

   2. In the Add authorization window, search for and click the data source or destination for which you want an authorization.

   3. Click Add authorization.

   Message

   (Optional) In the Message field, change the email message.

   Do not remove the {{links}} placeholder from the message field. The recipient needs these links to create the authorizations.

   Notification email

   (Optional) Enter any email addresses that you want to receive a notification when the authorization has been created.

7. Click Send access request.

As a result, an email is sent to the email address in the Email field to request the authorization or authorizations for you.

Authorization requests are shown in the Authorizations page with the status Access pending. If a pending authorization is not authorized within 7 days, it will expire. Click next to a pending authorization to see when it will expire.

The person granting the request will need to set permissions defining which items Adverity can access. If the data source has a lot of items, it may take a long time for the authorization items to load before the recipient can create the authorization.

After the authorization has been granted, an email notification will be sent to the email addresses you entered in the Notification email field. You can then use this authorization to collect data from the corresponding data source or load data into the corresponding destination.

Responding to an authorization request

If you receive an Adverity Authorization Request email, an Adverity user has asked you to give Adverity access to a data source. To grant this authorization, follow these steps:

1. Click the link in the email. This link is the name that the user who sent the request has given the authorization.

2. Use your credentials to create the authorization:

   • For some authorizations, you will be taken to the Adverity platform and asked to enter the required credentials (for example, a username and password).

   • For some authorizations, you will be taken to a login page for the corresponding data source where you can enter your credentials to authorize Adverity.

3. If this data source has multiple items, such as accounts or profiles, choose which items Adverity can access using this authorization. For more information, see What are authorization permissions? and Important information about Billing Objects. Select one of the following options:

   • Grant access to all items, including those created in the future - Select this option to give Adverity permissions to access all items associated with the credentials you have used. Adverity will also have access to all associated permissions created in the future.

   • Select specific items to which you want to grant access - Select this option to only give Adverity permissions to access the selected items. You will need to grant Adverity access to any associated items that are created in the future.

4. Click Authorize.

As a result, you have granted Adverity access to the data source or destination using your credentials. This authorization can now be used to create datastreams to fetch data from this data source or load data into this destination.

Viewing your existing authorizations

To see the authorization overview, follow these steps:

1. Go to the Authorizations page.

2. Click the name of the authorization you want to view.

As a result, you are taken to the authorization overview.

Your authorization overview

You can see all information about an authorization in Adverity's authorization overview as shown in the image below.

The authorization overview is divided into the following sections, in which you can see key information and perform certain actions.

Header area

In this area, you can perform the following actions:

• Next to the authorization name, click Edit name to change the name of this authorization.

• Click Re-authorize to re-authorize this authorization.

  You need to do this if the authorization status is Not granted. This can happen if the authorization expires, or if the data source requires authorizations to be updated regularly.

• Click More to perform the following actions. Not all actions will be available for all authorizations.

  • Click Test authorization to check that the authorization works.

  • Click See privacy information to open the privacy information about this authorization in a new window. This information is provided by the data source or destination, not Adverity.

  • Click See Oauth2 service details to open the OAuth2 details for this authorization in a new window. This information is provided by the data source or destination, not Adverity.

  • Click Update metadata to synchronize the metadata for this authorization. For more information, see Synchronizing metadata.

  • Click Debug to identify any problems with this authorization. This option is provided by the data source or destination, not Adverity.

  • Click Delete to delete the authorization.

    This will delete the authorization and all datastreams and/or destinations that use this authorization.

Attributes

In this section, you can see details of the authorization, such as which user created the authorization, in which workspace and when.

In this section, you can perform the following actions:

• If the authorization status is Access not granted, click Re-authorize to re-authorize Adverity's access to the data source or destination using this authorization.

• Click Edit notifications to set up email notifications about changes to this authorization. You will receive notifications to the selected email addresses for the following events:

  • The successful authorization of a new user

  • The re-authorization of existing users

• Click Edit metadata slack to change the metadata slack for this authorization.

Provides access to...

In this section, you can see the permissions for items that this authorization allows Adverity to access. In the image below, the authorization gives Adverity access to 1 Ad Account for the Facebook Ads data source.

• Click Manage to change the permissions for items that this authorization allows Adverity to access.

History

In this section, you can see changes that have been made to this authorization. The most recent changes are shown in the authorization overview. Click See all to see a full list of all changes made to this authorization.

To download the authorization history as a CSV file, click Export as file. Your download will start automatically.

Used by X datastreams

If this authorization gives Adverity access to a data source, here you can see a list of datastreams that use this authorization to collect data. If not all datastreams are shown, click See all to see a full list of the datastreams that use this authorization.

• Click + Create a datastream using this authorization to start collecting data from your data source using this authorization.

Used by X destinations

If this authorization gives Adverity access to an external tool, here you can see a list of destinations that use this authorization to load data into the tool.

• Click + Create destination to start loading data from Adverity into your external tool using this authorization.