Authentication

API keys

Create and revoke keys in the dashboard under API keys. A key looks like pc_live_xxxx… — the prefix pc_live_ followed by 32 random characters.

• The full key is shown once, when you create it. We store only a hash, so it can’t be shown again.
• The dashboard shows each key’s first 12 characters and when it was last used, so you can tell them apart.
• You can have up to 20 active keys. Use one per app or environment, so you can revoke one without touching the others.
• Revoking takes effect immediately.

Sending the key

Put the key in the Authorization header of every request. Only HTTPS is supported.

curl https://passcode.sh/api/v1/me \
  -H "Authorization: Bearer $PASSCODE_API_KEY"

When authentication fails

A missing, malformed, unknown or revoked key gets a 401 with the unauthorized error code and a WWW-Authenticate header. Failed attempts count against a per-IP rate limit. A valid key whose account has been disabled gets a 403 with account_disabled instead, so you know it isn’t a typo.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="passcode.sh API", error="invalid_token"
Content-Type: application/json; charset=utf-8
X-Request-Id: req_3kQ9mV2xL7pR4tN8bW1c

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key. Check for typos, or create a new key in the dashboard; revoked keys stop working immediately."
  }
}

Keeping keys safe

A key can spend your balance. Treat it like a password.

Server-side only

Never ship a key in a browser, mobile app or public repo. The API doesn’t send CORS headers, so browsers can’t call it directly anyway — proxy through your backend.

Environment variables

Load it from the environment or a secrets manager, e.g. PASSCODE_API_KEY.

Rotate

Create the new key, deploy it, then revoke the old one. No downtime needed.

Leaked?

Revoke it in the dashboard right away, then check your order history for anything you don't recognise.

Testing

There’s no separate test key. Where Demo inventory is available, use it: simulator orders behave exactly like real ones — charges, delays, codes, cancellations, refunds — with fictional numbers, and every response marks them demo: true.