Authentication

Each route of the Coritan API takes one kind of credential, and the part of the API it belongs to decides which. This page lists each credential, the header it goes in, how you get it and how long it lasts. A few routes take none, such as GET /auth/turnstile and the list of locations.

Access and refresh tokens, Organization credentials and Other keys describe each credential.

Sign in with POST /auth/login, sending email and password as JSON. Make your first API request walks through it with curl. The answer holds access_token, refresh_token, token_type (bearer) and expires_in.

Access token

Proves who you are on every Client API request, and on the Organization API for each organization you are a member of. It lasts 30 minutes unless Coritan changes the setting, and expires_in gives its lifetime in seconds.

Refresh token

Gets a new pair from POST /auth/refresh with the body {"refresh_token": "..."}, with no password, verification check or second factor. It lasts 30 days unless Coritan changes the setting. Each new pair holds a refresh token with a full lifetime; the one you sent keeps working until its own expiry.

Pending token

What the sign-in answers when two-factor authentication is on: mfa_required: true and an mfa_token that lasts 10 minutes (expires_in: 600). Send it as the bearer token to POST /auth/mfa/verify with {"code": "123456"}, and the answer holds the access and refresh tokens. Every other route refuses it with 401 and "error": "mfa_required".

Changing or resetting the password stops every token issued before it, and a suspended or closed account cannot use any token. The API has no sign-out route. Sign out and end sessions explains how to stop a token working.

Member access token

The same access token as the Client API. It reaches an organization's routes when you are its owner or a member, and your role decides what it may do. Without membership, a route answers 403 Not a member of this organization.

Staff console token

A console session for one organization, from POST /orgs/{org_slug}/staff/auth/login with your Coritan email and password. Its tokens start with ost_. The access token lasts 24 hours, and POST /orgs/{org_slug}/staff/auth/refresh swaps the refresh token, which lasts 30 days, for a new pair. It reaches every route a member's access token reaches. The actions that move money or end things also need a step-up in the last 10 minutes, which only a console session has: Confirm it is you lists them.

Customer token

A customer of an organization's storefront, from POST /orgs/{org_slug}/auth/login. The access token lasts 24 hours and the refresh token 30 days, and POST /orgs/{org_slug}/auth/refresh swaps them for a new pair. Sign in your storefront's customers has the details. A customer token never reaches the routes for members.

Organization API key

Lets your own systems call the Commerce API without a person signing in. An owner or admin creates it with POST /orgs/{org_slug}/api-keys; it starts with ct_, and the answer shows it once. Its scopes decide which routes it reaches, it has an hourly request limit (4,000 by default), and it can have a list of addresses it may be used from. No route outside the Commerce API reads it. Create organization API keys lists the scopes.

Publishable key

Names a store to the Store API, which serves shoppers, so the key can sit in your storefront's code. Create one with POST /orgs/{org_slug}/commerce/publishable-keys. A test key starts with pk_test_. A live key starts with pk_live_, and works once the store is live.

Send API key

Sends mail through one SMTP Relay service over HTTPS, and does nothing else. Create it on the relay, as Manage send API keys shows; it starts with mk_. The send API reads it from X-Api-Key only, never from Authorization. Send email over HTTPS has the requests.

Account API key

The keys on the API keys tab of Settings, which start with ct_. No route accepts them yet: sent as a bearer token, one answers 401 Invalid or expired token. Use an access token instead. Manage API keys explains what the keys are for today.

Coritan can put a verification check (Cloudflare Turnstile) on the forms that sign people in or give something away for free. GET /auth/turnstile says whether it is on:

{"enabled": true, "site_key": "..."}

While it is on, these routes also need a turnstile_token in the body. Only the check on a web page makes one, so a script cannot sign in with a password while the check is on.

Without a token, or with one that did not pass, the route answers 403 with {"detail": {"error": "turnstile_failed", "message": "Verification required"}}. The message is Verification failed for a token that did not pass.

Errors describes the shapes of detail, and Rate limits the 429 that too many failed sign-ins bring.