Authentication
API keys, scopes, test versus live, and rotating a key without an outage.
Sending a key
Every authenticated request carries the key as a bearer token.
curl https://api.payaider.com/v1/payment_intents \
-H "Authorization: Bearer sk_live_YOUR_KEY"A missing, malformed, unknown, revoked or expired key all return 401. The status never distinguishes them — only the code does — so a caller probing keys learns nothing from the status line.
Key types
| Prefix | Where it belongs | What it can do |
|---|---|---|
sk_live_… / sk_test_… | Your server, only. | Everything the account can do. Treat it like a database password. |
rk_live_… / rk_test_… | Your server, scoped down. | Per-resource None/Read/Write scopes, write implies read. Use these for anything that does not need full access. |
pk_live_… / pk_test_… | Nowhere yet — no endpoint accepts one. | Every authenticated route answers 403 publishable_key_not_permitted. payment:read is the same scope that lists your whole ledger, so browser-side retrieval waits on a per-object capability. Read payment state from your server, or link to the hosted checkout page. |
Test and live are parallel universes
A sk_test_… key against https://api.sandbox.payaider.com gives you the same API over separate data, backed by testnets. Nothing in test mode can touch live data.
A test key asking about a live object gets 404, not 403. That is deliberate: 403 would turn every id into an existence oracle across the boundary.
Scopes
Scopes are per resource with write-implies-read, so payment:create also reads payments and you never grant both. A key that lacks the scope gets 403 insufficient_scope — retrying will not help; mint a key that has it.
Rotation without an outage
- Create the replacement key. You see its secret once — store it immediately.
- Deploy it. The old key keeps working for 7 days (dual validity), so a rolling deploy is never a race.
- Watch the per-key request log until the old key goes quiet.
- Revoke the old key. Revocation is immediate and permanent.
Keys are stored hashed and are unrecoverable. If you lose one, roll a new one — nobody at Payaider can read yours back to you, which is the point.
Hardening worth doing on day one
- Put secret keys in a secret manager, never in source control or a client bundle.
- Use restricted keys per service, so a compromise is scoped to one job.
- Turn on the IP allowlist for server-side keys.
- Read the per-key request log occasionally: an unfamiliar IP is the earliest signal you will get.