API keys and rate limits
One arm holds the key out front. Scope every key to a single project, rotate or revoke it without a second of downtime, and stay inside rate limits you can plan around. Both legacy and v2 keys work today.
Legacy and v2 keys
Two models live side by side. Pick one per project; v2 is the one we'd reach for.
Legacy
One key per project. RotateAPIKey replaces it with a new one, which means there's a moment where the old key stops and the new one starts.
v2
Several named keys per project. CreateAPIKey adds one. RevokeAPIKey kills a single key on its own, and GetProjectByAPIKey resolves which project a key belongs to. This is what lets you rotate without a gap.
Both are active. We recommend v2 for the multiple keys and the one-at-a-time revoke.
Scoped to projects
A key belongs to one project inside your organization. It can't read or move money for another. Give each project, and each environment, its own key. Then a leak stays boxed in: the blast radius is that one project, not your whole account. Who holds which key is governed by roles, over on account security.
Rotate and revoke
On v2 the move is to create the next key first, cut traffic over to it, and only then call RevokeAPIKey on the old one, which means there is never a window where the integration is dead. RevokeAPIKey takes effect at once. That makes it your panic button the moment a key looks exposed. On legacy, RotateAPIKey swaps the single key in place. Either way, rotate on a schedule and revoke on the first hint of a leak.
Requests are rate-limited. Go over the ceiling and you get a standard HTTP error, not a silently dropped call. We won't print a specific number here until it's confirmed in the gateway code, because a wrong limit is worse than none. Build with backoff on the error and you're covered either way.
Exact limits: [TBD from code]
Authenticate a request
Pass your key in the X-Api-Key header on every call. The example shows a payment create against POST /v1/payments. Keep the real key on your server, never in the browser; the example uses an sk_live_... placeholder in place of a live key.
curl -X POST https://api.suward.com/v1/payments \
-H "X-Api-Key: sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_abc_1" \
-d '{"amount":"25.00","asset":"USDC"}'Best practices
Short list, all of it worth doing.
- 01
Keep keys server-side. A key in browser or app code is a key already leaked.
- 02
One key per project and per environment. Production and staging should never share a secret.
- 03
Rotate on a schedule, and revoke the instant a key looks exposed.
- 04
Never commit a key to git. Plenty of breaches start with a secret pushed to a public repo. Use a secrets manager or environment variables instead.
API keys FAQ
Legacy gives one key per project and RotateAPIKey replaces it. v2 gives several named keys per project, created with CreateAPIKey and revoked one at a time with RevokeAPIKey. That difference is what makes zero-downtime rotation possible.
Create the new key with CreateAPIKey first. Switch your traffic over, confirm it works, then revoke the old one with RevokeAPIKey. The integration never sees a gap.
Revoke it immediately with RevokeAPIKey, then issue a replacement with CreateAPIKey. Because keys are scoped per project, the exposure is limited to that one project, and the rest keep running.