Authentication

Send your API key in the Authorization header. The API has no other way to sign in, and all four queries need the key.

What does the header look like?

Put the word apikey, one space, then the key.

Authorization: apikey YOUR_API_KEY

• The word apikey is not case-sensitive.
• A Bearer header does not work. The API reads only the apikey form.
• The key is the full value that the product shows one time, when an Admin creates the key. The 8 characters in the Key column of the API keys tab are not the full key.

To create a key, see Create and revoke an API key.

What can a key read?

A key reads the data of the workspace where an Admin created it. A key cannot read a different workspace.

A key can have a channel scope. The scope depends on the choices of the Admin who created the key, so two keys of one workspace can return different rows.

• A key with no channel scope reads each channel of the workspace.
• A key with a channel scope reads only its channels in modeledMetrics, reportedMetrics, and channelNames.
• The channel scope does not change the result of models.

If a query returns fewer channels than you expect, ask an Admin to check the Channel scope column of the key.

When does a key stop working?

A key stops working in two cases.

• An Admin revokes the key. The key stops working immediately.
• The key passes the date in its Expires column. A key with Never in that column does not expire.

After each request that authenticates, the product updates the Last used column of the key.

What does the API return when the key does not work?

The API returns the same error for a missing header, a header in a different form, a key that does not exist, a revoked key, and an expired key. The HTTP status is 200, the data field is null, and the errors list has one entry.

Response

{
  "errors": [
    {
      "message": "Authentication failed. Check your token.",
      "locations": [{ "line": 1, "column": 3 }],
      "path": ["channelNames"]
    }
  ],
  "data": null
}

The message uses the word token for the API key. The values of locations and path depend on your query.

Because the status is 200, do not use the HTTP status to find a failed request. Read the errors field. See Errors.

Repeated failures from one IP address cause a temporary block. See Limits.

How do you keep a key safe?

• Keep the key in a secret store or an environment variable. Do not put the key in source code.
• Call the API from a server. Code that runs in a browser shows the key to each visitor.
• Give each integration its own key, so you can revoke one key and keep the others.