Client API: Authentication

Register, sign in, refresh tokens and manage your profile, and see or sign out the devices signed in to your account. Send the access JWT from sign in as a Bearer token.

Base URL: https://api.coritan.com/api/v1. Paths below are complete.

To try these requests in the browser, open the interactive Client API reference.

POST /api/v1/auth/forgot-password

Issue a reset link by email. The answer is the same whether or not the address has an account, so the form cannot be used to probe for one.

application/json (required)

POST /api/v1/auth/login

application/json (required)

POST /api/v1/auth/logout

Sign this device out on the server.

Send the access token as the bearer, the refresh token in the body, or both: an expired access token is fine when the refresh token names the session. A refresh token from before sessions existed is recorded as signed out, so it can never refresh again.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json

GET /api/v1/auth/mailbox-availability

Live check behind the sign-up form's username field.

GET /api/v1/auth/mailbox-domain

Whether this storefront offers a mailbox on its own mail domain at sign-up, and which domain. Public: the form reads it before anyone has an account.

GET /api/v1/auth/me

The signed-in account. credit_balance is in credit_currency, always USD; currency is the currency we charge the account in and never labels the balance. support_session says the token is a support session Coritan support opened as the account, with its mode and when it ends, so the page can say so; it is null for the account's own sign-in.

Authentication: an access token, sent as Authorization: Bearer <token>.

Fields of a 200 response:

PUT /api/v1/auth/me

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

Fields of a 200 response:

GET /api/v1/auth/me/api-keys

Authentication: an access token, sent as Authorization: Bearer <token>.

A 200 response is a list; each item has these fields:

POST /api/v1/auth/me/api-keys

Permissions are <area>:read or <area>:write, and the allow-list holds addresses and CIDR ranges; anything else is a 422 that names it (app/services/api_key_auth.py).

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

Fields of a 200 response:

DELETE /api/v1/auth/me/api-keys/{key_id}

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/auth/me/password

Change the password. Every other session is signed out, and this device gets a new token pair in the answer, since the change makes every token issued before it invalid.

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

GET /api/v1/auth/me/staff-link

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/auth/me/staff-link

Authentication: an access token, sent as Authorization: Bearer <token>.

application/json (required)

DELETE /api/v1/auth/me/staff-link

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/auth/refresh

A new token pair for a refresh token, which is then used up (app/domains/auth/sessions.py).

application/json (required)

Fields of a 200 response:

POST /api/v1/auth/register

Create an account and sign it in. Send exactly one of email and mailbox_local_part. With a mailbox, the address is the local part on the storefront's sign-up domain, and the account and its mailbox are made together.

One network, an IPv4 address or an IPv6 /64, can make 3 mailboxes an hour and 5 a day, counting the ones claimed later in webmail; past that the answer is 429. A network an address rule blocks, a hosting, VPN, proxy or Tor network when the platform refuses those, and a network whose earlier mailbox was paused in the last 7 days get 403 with the reason. A taken address is 409, a name that cannot be used 422, a storefront that offers no mailbox 404, and a mail service that cannot take a new mailbox right now 503.

application/json (required)

Fields of a 200 response:

POST /api/v1/auth/reset-password

application/json (required)

GET /api/v1/auth/sessions

Where this account is signed in, newest activity first.

current marks the session this request came from. country_code is where the address places, or null when nothing can place it. A device signed in before sessions were recorded appears after its next refresh. support_session is true for a session Coritan support opened as the account, which lasts 30 minutes; support_mode is then read_only or full, and its address and device are the support agent's.

Authentication: an access token, sent as Authorization: Bearer <token>.

POST /api/v1/auth/sessions/revoke-others

Sign out everywhere except this device.

A device whose token predates sessions has no row to keep, so it gets a new session and its token pair in the answer; the dashboard stores it.

Authentication: an access token, sent as Authorization: Bearer <token>.

DELETE /api/v1/auth/sessions/{session_id}

Sign out one device. Signing out this device's own session works too; the dashboard then clears its tokens.

Authentication: an access token, sent as Authorization: Bearer <token>.

GET /api/v1/auth/turnstile

Public: whether the platform's auth and order forms must render a check, and with which site key (no auth).

enabled and site_key are all a page on Cloudflare Turnstile gets. While wicket.platform_forms is on the answer also carries provider (wicket) and script_url (the Wicket loader, already set to explicit rendering): the page loads that script and draws the widget with the same render, reset and remove calls from window.wicket. The token it hands back goes in turnstile_token on the form's request, whichever provider made it.