API authentication

The authentication model

All API requests authenticate with a bearer token. Tokens are workspace-scoped: a token authenticates as the workspace, with the scopes you assigned at creation.

Authorization: Bearer ad_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

There is no OAuth. There is no per-user impersonation. Every request acts as the workspace identified by the token.

Token format

Tokens have a prefix that identifies their environment:

• ad_live_ — production tokens.
• ad_test_ — sandbox tokens that don't consume live quota or create audit-log entries.

The remainder is 32 characters of URL-safe random.

Creating a token

See API keys for the UI flow. Programmatic creation is not yet supported — keys are created through the dashboard only.

Scoping

At creation, you choose:

• Companies. All companies in the workspace, or a single company (recommended).
• Read or write. Write endpoints are arriving incrementally.

Single-company scoping limits the blast radius of a leaked key. If you only integrate with one company, scope to it.

Per-request example

curl https://api.aidomination.app/v1/audits \
  -H "Authorization: Bearer $AD_TOKEN" \
  -H "Accept: application/json"

The response:

{
  "data": [
    {
      "id": "aud_01HSXX",
      "companyId": "cmp_abc",
      "headlineScore": 78,
      "completedAt": "2026-05-12T08:00:00Z"
    }
  ],
  "pagination": { "nextCursor": null }
}

Rotation

Best practice: rotate every 90 days. From the dashboard:

1. Settings → API → Keys → [key] → Rotate.
2. The new value is shown once.
3. The old value is invalidated immediately.

For zero-downtime rotation, create a new key, deploy your services using it, then revoke the old one.

Revoking

Settings → API → Keys → [key] → Revoke. Within 60 seconds, requests using that key return:

{ "error": { "code": "invalid_key", "message": "API key is invalid or revoked." } }

Revocation is logged to your audit log.

Detecting compromise

If a key leaks (committed to a public repo, shared in a Slack message that landed in the wrong place):

1. Revoke immediately.
2. Check the audit log for any api.request entries that don't match your usage pattern.
3. Generate a new key.
4. Audit any data the leaked key could read (the scopes tell you the blast radius).

We do NOT scan the public web for leaked keys. Use a secrets-scanning service (GitHub secret scanning, TruffleHog, etc.) on your own repos.

Storage on our side

We store only a salted hash of the token. The plaintext exists for a few seconds during creation, never persisted. Compromised dashboard access does not reveal existing tokens — only lets the attacker create or revoke.

Storage on your side

Recommendations:

• Never commit tokens to source control. Use .env files (gitignored), or a secrets manager.
• Use ad_test_ keys in CI to avoid production audit-log noise.
• Rotate after any team member with key access leaves.
• Scope to single companies where possible.

What's NOT supported

• HMAC request signing. Bearer tokens only, for now.
• OAuth 2.0 for end users. Coming with the public-app marketplace.
• mTLS. Not on the roadmap.
• User-impersonation tokens. Out of scope — see Impersonation for the support-only feature.