Authentication and Authorization

API authentication and authorization is based an Adspert users. A user may have one or multiple API keys which can be used to request API tokens (similar to access tokens in an OAuth context). Regular API interaction is done with API tokens.

Authentication Modes

Non-public routes use one of the following authentication modes.

api-key

This mode expects a basic auth Authorization header using an API key ID and secret.

For a key ID SaMpLE0KeY and a secret sAmPle0SeCrEt4321, the header would look like this:

Authorization: Basic U2FNcExFMEtlWTpzQW1QbGUwU2VDckV0NDMyMQ==

Important

API keys are long-living credentials which should be handled carefully. They are only needed to create short-living API tokens which are used for most API routes.

api-token

This mode expects the Authorization header to contain an API token in Bearer format.

For the API token 433126ffa47f453c21f26d9f15ea11f5... the header would look like this:

Authorization: Bearer 433126ffa47f453c21f26d9f15ea11f5...

API tokens have a limited life-time, ranging from a few hours to a few days, depending on their usage.

Authorization

Which routes and data items may be accessed by a user depends on the user’s access level. A route’s access level (and potential further access level restrictions on certain data items) is specified in the detailed routes documentation.

The following access levels exist:

Access Level	Description
`none`	This access level means that a route does not have any requirements on a user’s access level. It is used on routes which do not need an authenticated Adspert user.
`user`	The access level of a regular Adspert user without special privileges.
`customer-admin`	The access level of a user who is an administrator of an Adspert customer account. Customer admins can invite new Adspert users, connect new advertising accounts, and manage permissions for other users of the same customer.

Access Level Elevation

On some resources certain fields require a higher access level than the resource itself. For instance all users can get the name of the customers they have access to, but only customer admins can see billing related data.

In order to use those higher access level fields, the request to the API explicitly needs to elevate the access level to that higher level, using the header X-Adspert-Access-Level, with a value form the table above.

The elevation basically provides a single endpoint in multiple variants, each with different field sets. API clients need to be explicit about which variant they are interested in!

If the access level elevation is used, only data for the Adspert customers where the authenticated user has a corresponding access level are included in the response data.