Authentication
Every request to shrug.ai is authenticated with a Bearer API key in the
Authorization header:
Authorization: Bearer shrug_sk_your_key_here
Keys look like shrug_sk_ followed by 43 URL-safe characters. Create and revoke
them from Dashboard → API keys. A key’s full value is shown once, at
creation time — store it somewhere safe; shrug.ai keeps only a hash and can never
show it to you again.
401 vs 402 — the divergence that matters
shrug.ai deliberately separates “your credential is wrong” from “your account is out of quota.” They are different problems with different fixes, so they get different status codes:
| Status | Meaning | What to do |
|---|---|---|
| 401 Unauthorized | The API key is missing, malformed, revoked, or unknown. | Fix your key. Check the Authorization header is present and spelled Bearer shrug_sk_…, and that the key hasn’t been revoked. A new key will not help if the old one was simply mistyped. |
| 402 Payment Required | The key is valid, but the account is over its free quota and has no active subscription. | Subscribe. The key itself is fine — add a payment method in Dashboard → Billing to continue past the free tier. |
The practical rule: 401 means change the key; 402 means change the plan. Never retry a 401 with the same key, and never rotate a key to resolve a 402.
// 401 — the key is the problem
{ "error": { "type": "authentication_error", "message": "invalid API key" } }
// 402 — the plan is the problem
{ "error": { "type": "quota_exceeded", "message": "account over free quota" } }
See Errors & limits for the complete status-code table.