Authentication
API keys (server-to-server)
Section titled “API keys (server-to-server)”Send a secret key as a bearer token:
Authorization: Bearer rk_test_4eC39HqLyjWDarjtT1zdp7dc...Keys are scoped to one organization and one environment, stored only as a hash, shown once, and revocable at any time from Developers → API keys. Never ship a secret key to a browser or mobile app.
OAuth client credentials
Section titled “OAuth client credentials”Prefer short-lived tokens? Create an OAuth client in the dashboard, then exchange its credentials for a 1-hour token:
curl https://api.rivecard.com/v1/oauth/token \ -H "Content-Type: application/json" \ -d '{"grant_type":"client_credentials","client_id":"oac_...","client_secret":"rcs_test_..."}'# → { "access_token": "rat_test_...", "token_type": "Bearer", "expires_in": 3600, "environment": "test" }HTTP Basic (client_id:client_secret) works too.
End-user connect
Section titled “End-user connect”To act for one of your users, connect them with a one-time code:
POST /v1/connect/start { "email" }(with your org credential) emails them a 6-digit code. In test mode no email is sent and the code is always111111.POST /v1/connect/verify { "email", "code" }returnsaccess_token(act_…, 1 h) and a rotatingrefresh_token(rct_…, 30 days).POST /v1/connect/refresh { "refresh_token" }rotates both. Re-using a spent refresh token revokes the whole connection.
Dashboard sessions
Section titled “Dashboard sessions”People sign in at auth.rivecard.com with an emailed code or a passkey. The session is an HttpOnly, Secure,
SameSite=Lax cookie for .rivecard.com. Cookie-authenticated writes must also send the X-CSRF-Token from
GET /v1/auth/session. Google and GitHub sign-in are planned.
| Role | Can |
|---|---|
| owner | everything, including deleting the organization |
| admin | manage team, live mode, audit log |
| developer | API keys, webhooks, cards (test and live writes need admin for live) |
| viewer | read-only |