API keys

The Asky API authenticates with a workspace API key sent as a bearer token.

curl https://api.askylabs.com/v1/brands \
  -H "Authorization: Bearer asky_sk_..."

There is no other authentication method. Cookies, session tokens, and query-string keys are not accepted, so a key can never leak through a browser history, a proxy log, or a Referer header.

Key format

asky_sk_TFqPk3nZ8vN2mR7wL4xB9cD1eF6gH0jK5sT8uV3yA2b
└──┬──┘└────────────────────┬─────────────────────┘
 prefix              random + checksum

The asky_sk_ prefix identifies the key as ours, which is what lets secret-scanning tools recognise one if it is ever committed to a public repository. The remainder is 256 bits of randomness plus a checksum, so a malformed or truncated key is rejected without a database lookup.

We store only a salted hash of the key. We cannot show it to you again, and we cannot recover it for you. If you lose a key, roll it.

In Settings, and anywhere we refer to a key, it appears as its last four characters:

asky_sk_…yA2b

The tail rather than the beginning, deliberately. Truncation in logs, error messages and terminal output keeps the start of a string, so identifying keys by their opening characters would mean the fragment on your screen is the same fragment most likely to leak by accident.

Keys belong to the workspace

An Asky API key belongs to the workspace, not to the person who created it.

This matters in practice. The key keeps working when its creator leaves your team or loses access, so an integration does not break because of a personnel change. Any owner or admin of the workspace can see the key in Settings, roll it, or revoke it. The person who created it is recorded for attribution and shown in the key list.

A key can read data for exactly one workspace. To integrate with two workspaces, create one key in each.

What a key can reach

Three boundaries apply to every request, in this order.

Workspace

The key’s workspace is fixed at creation and cannot be changed. Any request for data outside it returns 404 not_found rather than 403, so the API never confirms that a resource you cannot see exists.

Brands

By default a key reaches every brand in its workspace, including brands added later. A key may instead be restricted to specific brands, which is useful when an agency runs several clients in one workspace and wants an integration or a hand-off to reach only one of them.

GET /v1/brands returns only the brands a key may reach, so discovery never advertises something a later call would refuse.

Scopes

Every key carries a set of read scopes that map to areas of your data.

Today every key is issued with the full read set, so you do not choose scopes when creating one. They appear on GET /v1/me and in error messages so your integration can reason about them, and so narrower keys can be offered later without changing how requests work.

Using a key with an AI agent

An Asky API key works anywhere a static bearer header does, which includes agent frameworks, automation tools such as n8n, and CI jobs.

If you want an AI assistant to query Asky directly, the MCP server is usually the better door. It reads the same data, but it authenticates through a browser sign-in rather than a stored secret, so there is no long-lived credential sitting in a config file, and access follows the person rather than the workspace.

Verifying a key

GET /v1/me returns the identity behind the key: its name, workspace, scopes, brand access, and who created it. It is the fastest way to confirm a deployment picked up the right secret, and the check to run after a key roll.

curl https://api.askylabs.com/v1/me -H "Authorization: Bearer $ASKY_API_KEY"

Failed authentication

These are deliberately distinct so your logs point straight at the cause. See error handling.