Skip to content

Authentication

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.

Prefer short-lived tokens? Create an OAuth client in the dashboard, then exchange its credentials for a 1-hour token:

Terminal window
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.

To act for one of your users, connect them with a one-time code:

  1. 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 always 111111.
  2. POST /v1/connect/verify { "email", "code" } returns access_token (act_…, 1 h) and a rotating refresh_token (rct_…, 30 days).
  3. POST /v1/connect/refresh { "refresh_token" } rotates both. Re-using a spent refresh token revokes the whole connection.

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