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, Account API keys, 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, and the one you sent stops working. Sending it again more than a minute later signs the session out, so keep the new refresh token each time.

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. POST /auth/logout signs out the session of the access token you send as the bearer, or of the refresh token in the body {"refresh_token": "..."}. Sign out and end sessions explains how to stop a token working.

An account API key lets a script call the Client API as you, without your password or a second factor. Create one on the API keys tab of Settings. It starts with ct_, and Coritan shows it only once. Send it in the header an access token uses:

curl -s "https://api.coritan.com/api/v1/services/?limit=5" \
  -H "Authorization: Bearer $CORITAN_TOKEN"

• A key with any Write permission can make every change you can, whatever area the permission names.
• A key with only Read permissions can send GET and HEAD requests, and POST /checkout/quote, which prices an order without placing it. Any other request answers 403 with "code": "api_key_read_only".
• A key with an IP allow-list works only from the addresses on it.
• No key can reach your profile and sign-in settings (/api/v1/auth/...), your team, webmail or your organizations (/api/v1/orgs/...). No key can act for another account with the X-Coritan-Account header either. What no key can do lists the routes.
• A WebSocket, such as a server's live console, takes an access token.

A key works until you revoke it, and changing your password leaves it working. A suspended or closed account cannot use its keys. Manage API keys covers creating, limiting and revoking keys, and Authentication errors lists the refusals.

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.

Coritan can put a verification check 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": "..."}

An answer like that one is a Cloudflare Turnstile check. When Coritan's own check, Wicket, draws it instead, the answer also names Wicket and gives the address of its script:

{"enabled": true, "site_key": "wk_...", "provider": "wicket", "script_url": "https://wicket.coritan.com/v1/api.js?render=explicit"}

Either way the token goes in turnstile_token. While the check 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.