Skip to main content
The Awardee API authenticates with bearer tokens. Each key belongs to exactly one organization and can be revoked or paused independently. Rate limits are enforced per organization — every key in an org shares one bucket.
Zapier and OAuth (preview). Awardee now also accepts OAuth access tokens (prefix awo_live_) on every v1 endpoint, used by the Zapier integration and third-party apps acting on behalf of a member. OAuth tokens carry user-scoped permissions and require a requiredScopes check per endpoint, while personal API keys (prefix aw_live_) remain org-wide and unscoped — pick the model that matches your integration. Personal keys are still the canonical method for first-party automations; the OAuth flow is documented at /oauth/authorize and /api/oauth/token.

​
Key format

Live keys start with aw_live_ followed by 32 hex characters: 
aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e
The full secret is shown once, at the moment of creation. The dashboard stores only a hashed lookup prefix and the last four characters after that. Lose the secret and you must rotate the key.

​
Sending the key

Set the Authorization header on every request. The scheme is Bearer. 
curl https://api.awardee.dev/v1/me \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"
Treat API keys like any other secret. Never embed them in client-side JavaScript, mobile binaries, public repositories, or build artifacts. If a key leaks, revoke it immediately from the dashboard and create a fresh one — there is no partial-rotation path.

​
Creating a key

In the dashboard, open Settings → API keys → New key. Each key has:
  • Name. Free-form. Use it to identify the integration that holds the key (crm-sync-prod, analytics-etl, dev-laptop-ethan).
  • Expiration. Optional. If set, the key returns 401 api_key_expired after that timestamp. Recommended for short-lived integrations and CI.
  • Rate limits. Apply to the whole organization, not the individual key — every credential in the org shares one bucket (default 60 requests per minute and 1,000 per hour, configurable by Awardee staff). See Rate limits.
You can create as many keys as you need. Each has its own lifecycle, so revoking one does not affect the others — but all keys in the org share the same rate-limit bucket, so adding keys does not raise your throughput.

​
Revoking and pausing

Permanent. The key is destroyed and cannot be reactivated. Subsequent requests get 401 api_key_revoked. Use this when a key has been exposed, when an integration is retired, or when an employee leaves.

​
Auth error codes

Every authentication failure returns a JSON envelope with a stable error code. Branch on the code, not on the human-readable message.
StatusCodeMeaningFix
401missing_api_keyNo Authorization header on the request.Add Authorization: Bearer aw_live_….
401invalid_api_keyHeader present but value isn’t a recognized key.Check for typos, trailing whitespace, or a key from a different environment.
401api_key_revokedThe key was revoked in the dashboard.Mint a new key and update the integration.
401api_key_expiredThe key passed its expires_at.Mint a new key or extend the expiration.
403api_key_pausedThe key exists but is paused.Resume it in the dashboard, or use a different key.
Example: 
{
  "error": "invalid_api_key",
  "message": "API key is invalid.",
  "request_id": "req_8fK2x9aLp0qR"
}

​
Rotation

There is no in-place rotation. To rotate:
1

Create the new key

Mint a fresh aw_live_… and store it in your secrets manager alongside the old one.
2

Deploy

Roll your services so they read the new key.
3

Revoke the old key

Once traffic on the old key drops to zero, revoke it in the dashboard.
The X-Request-Id response header makes this rollout observable. Watch the dashboard’s “Requests last hour” counter on each key to confirm the cutover.

​
Scoping

Keys are org-scoped, not user-scoped. They have full read/write access to every resource in the org that owns them. Per-resource scopes are not currently supported. If you need finer-grained access (e.g. read-only, knowledge-base-only), create a separate org for that integration or contact support.