Start

Authentication

Every request sends an API key and the id of the brand it is for. A key belongs to one brand, and its scopes decide which endpoints it may call.

The two headers#

Header	Value
Authorization	The API key, sent bare: `Authorization: mta_…`. `Basic <key>` and `Bearer <key>` are accepted too, and so is `Basic` with the base64 of `<key>:`, which some HTTP clients send.
Data-Client-ID	The brand id, a UUID. The app shows it on the API Keys page, labelled Data-Client-ID.

Request

curl "https://mta.growthdept.ai/api/v1/exports/account" \
  -H "Authorization: $MTA_API_KEY" \
  -H "Data-Client-ID: $MTA_BRAND_ID"

The one endpoint that takes neither header is the file download: its signed link is the credential. See Download an export file.

API keys#

An owner or admin of the brand's organization creates keys in the app, under Settings > API Keys. Other members see the page read-only.
A key is mta_ followed by 40 characters. It is shown once, when it is created: copy it into your secrets store then. MTA keeps only its SHA-256 hash and its first 12 characters, which the page shows so you can tell keys apart.
A key belongs to one brand. Sent with another brand's id, it is treated as unknown.
Give each key a name after what uses it, such as “Warehouse reader”, so you know which one to revoke. Keys can be renamed later.
The page shows when each key was last used, updated at most once a minute, and a history of who created, renamed and revoked keys.

Scopes#

You tick a key's scopes when you create it. Give a key only what its job needs: a warehouse reader needs export:read and nothing else.

Scope	Short name	In the app	Allows
export:read	export	Read your attribution data	Every `GET /exports/*` endpoint and `POST /exports/data-export`.
orders:write	orders	Send orders	`POST /orders`.
spend:write	spend	Send ad spend	`POST /spend`.
views:write	views	Send matched ad views	`POST /views`.

The create dialog starts with export:read, orders:write and spend:write ticked. views:write is offered but never ticked for you, since a key that sends partner views is made for that partner.
A key needs at least one scope. Requests that create keys accept the short names in place of the full ones.
GET /exports/account answers any valid key, whatever its scopes, so a client can check which scopes it has.

401 or 403#

Status	When
401	The key is missing, unknown or revoked; it belongs to another brand than `Data-Client-ID`; `Data-Client-ID` is missing or not a UUID; or the brand is being deleted.
403	The key and brand are fine, but the key lacks the scope this endpoint needs. The answer names the scope.

The reason is in detail. POST /orders, /spend and /views repeat it in error, their older field:

401 from an export endpoint

{ "detail": "Unauthorized: send a valid API key in Authorization and its brand id in Data-Client-ID." }

403 from POST /orders

{
  "detail": "this API key lacks the orders:write scope",
  "error": "this API key lacks the orders:write scope"
}

A 401 never says which part was wrong, so check the key and the brand id together. Every other status is on Errors.

Revoking a key#

An owner or admin revokes a key on the API Keys page. The next request with it gets 401. A revoked key cannot be restored: create a new one and update the client.

Download links outlive the key

Download links already handed out keep working until they expire, up to an hour, because a link does not check a key. If a key leaks, revoke it, then treat links fetched with it as exposed for the next hour.

Keys for partners#

To let a partner on Growth Dept's list read your exports, grant it under Settings > Data Sharing. The partner gets a key with export:read only, for this brand only, shown once so you can pass it on. Revoking the grant revokes the key.

Questions about the API: support@growthdept.ai.