Authentication and API keys
Authenticate every /v1 request with a secret API key sent as a Bearer token.
The Teyra Pay API uses secret API keys. Send the key in the Authorization header of every request:
curl https://api.teyra.co/v1/payments \
-H "Authorization: Bearer sk_test_4f9a..."Requests without a valid key fail with 401 unauthorized. All requests must use HTTPS.
Key types
| Prefix | Mode | Use |
|---|---|---|
sk_test_ | Test | Development and staging. Creates test payments that move no money. Objects have "livemode": false. |
sk_live_ | Live | Production. Real payments. Objects have "livemode": true. Requires an approved account. |
The key decides the mode: the base URL (https://api.teyra.co) is the same for both. Test and live data are completely separate, so a test key cannot read a live payment and the other way round. See Test mode and live mode.
Create and manage keys
Keys are managed in the dashboard under Developers → API keys. Users with the Owner, Admin or Developer role can manage keys.
- Click Create key, give it a name (for example
production-web) and pick Test or Live. Creating a live key asks for your password. - Copy the secret immediately. Teyra Pay stores only a hash and shows the full key once. Afterwards the dashboard shows only its prefix, such as
sk_test_4f9a, and when it was last used. - Put the key in your server's secret store or environment variables.
To rotate a key, create a new key, deploy it, confirm traffic uses it (check last used), then revoke the old key. A revoked key stops working immediately.
Keep keys safe
Secret keys are for servers only
Anyone with a secret key can create payments and refunds on your account. Never embed it in browser JavaScript, a mobile app, a public repository or a support ticket.
- Use a separate key per system (website, ERP, plugin) so you can revoke one without affecting the others.
- Keep live keys out of development machines and CI logs.
- If a key leaks, revoke it in the dashboard right away and create a new one.
Rate limits
Each secret key can make up to 1,200 requests per minute to /v1. Every response carries the current state of the limit:
| Header | Meaning |
|---|---|
x-ratelimit-limit | Requests allowed per minute. |
x-ratelimit-remaining | Requests left in the current minute. |
x-ratelimit-reset | Seconds until the window resets. |
Above the limit, requests fail with 429 rate_limited, a Retry-After header and details.retry_after_seconds. Wait that long, then retry with the same Idempotency-Key. If you need a higher limit, contact support@teyra.co.
Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | The Authorization header is missing, malformed, or the key is revoked or unknown. |
| 403 | forbidden | The key is valid but cannot perform this request. |
| 403 | merchant_not_active | A live key was used before your account was approved and activated, or the account is suspended. Use a test key until approval. |
| 429 | rate_limited | Too many requests with this key. See Rate limits. |
See Errors for the full list.