Organization API: Customer Authentication: Auth

Part of Customer Authentication.

POST /api/v1/orgs/{org_slug}/auth/checkout-session

Give a visitor at checkout a customer session from their email address.

• An address with no account and verify: false: we make the account with no password and the details sent, and answer 201 {"status": "created", access_token, refresh_token, expires_in, customer}. We email a link to choose a password (account_set_password, good for 3 days). When your organization requires two-factor authentication, the answer holds the set-up step (mfa_token with mfa_setup_required) instead of a session.
• An address with no account and verify: true: we email a code and answer 200 {"status": "code_sent", challenge, email_hint, expires_in, resend_after, new_account: true}. POST /auth/code/verify then makes the account and signs the customer in.
• An address that has an account: we email a code to sign in and answer 409 with detail {"error": "account_exists", "message", challenge, email_hint, has_password, expires_in, resend_after}, and never a session. The customer gives the code to POST /auth/code/verify, or their password to POST /auth/login.

The names, company, country and address are saved only on an account this request makes; otherwise save them after sign-in. The first proof of the address (a code, or the password link) ends the session this request returned.

Refusals as for POST /auth/code/request, and 429 when one network made 20 accounts here in the last hour.

application/json (required)

POST /api/v1/orgs/{org_slug}/auth/code/request

Email the customer a 6-digit code to sign in with.

identifier is an email address or a Minecraft username. An address with an account gets a code to sign in to it. An address with no account gets one too, and new_account is true: giving the code makes the account. Both answers show where the code went in email_hint.

A name finds the active account that first bought for that player or named it in POST /portal/players (a later customer who uses the same name does not take it over), and then the account whose own username it is; the code goes to that account's address. The answer for a name is the same whether or not an account uses it: email_hint is null, new_account is false, and challenge is always present. For a name no account uses, no email goes out and no code can open the challenge. Names count against the same limits as addresses, by name and by network.

Send challenge and the code to POST /auth/code/verify. A code works for 10 minutes and 5 tries. An address can ask for another after 30 seconds and gets at most 5 codes in 15 minutes, and one network at most 20 an hour.

Refusals: 400 for an identifier with @ that is not an address; 403 as sign-up refuses a new address (a blocked email domain, the customer limit) and for an account that is banned, suspended or closed; 403 turnstile_failed; 429 with Retry-After while the address or the network must wait; 503 when we cannot send your organization's email.

application/json (required)

Fields of a 200 response:

POST /api/v1/orgs/{org_slug}/auth/code/verify

Sign in with the code from the email.

The answer is the one POST /auth/login gives: a session (access_token, refresh_token, expires_in, scopes), or the second-factor step (mfa_token with mfa_required, or mfa_setup_required when your organization requires two-factor authentication and the customer has not set it up).

The code proves the address. When no account has it, we make one with no password, send your welcome email, and your webhooks receive customer.created. The first time an account's address is proven, every session made before ends, such as one a checkout made for an address its owner had not proven yet. On an account with no password, the same step removes an authenticator, which only such a session can have added, and applies invites to share a server with the address.

Refusals: 400 with detail.error wrong_code, expired or used, a message to show and attempts_left. The fifth wrong code spends the challenge. 403 as for POST /auth/code/request.

application/json (required)

POST /api/v1/orgs/{org_slug}/auth/forgot-password

Email a link that sets a new password, to the address of an active account.

The answer is always 200 {"message": "If the account exists, we issued a reset link"}, whether or not the address has an account, and the link works for 2 hours. Only the newest forgot-password link works. It never replaces a link we made on our own, such as the set-password button of an account move, so a stranger who types an address cannot void the link its owner was sent.

429 when one network has asked 10 times in an hour. One address gets 3 links an hour: later requests for it answer the same 200 and send nothing. Both counts include addresses that have no account, so neither says whether an address has one.

application/json (required)

POST /api/v1/orgs/{org_slug}/auth/login

Password sign-in with an email address or a username.

Send identifier (or email or username) and password. We answer 200 with a session (access_token and refresh_token), or with the second-factor step (mfa_token) when the account or the organization asks for one.

A name that is no customer's username may be a Minecraft player name: it signs in the active customer who first bought for that player or named it in POST /portal/players. A later customer who uses the same name does not take it over.

The password is checked by check_password: a hash imported from a WordPress store ($wp$, phpass $P$ or $H$, plain MD5) opens the account like a bcrypt one, and is replaced by a bcrypt hash of the same password in this sign-in's transaction.

Every refusal has detail, a sentence to show, and code, a word to act on:

• 401 invalid_credentials: the login or the password is wrong.
• 401 no_password: the account has no password yet. POST /auth/forgot-password emails the link that sets one, and a storefront with a code form (POST /auth/code/request) can offer that as well.
• 429 rate_limited, with Retry-After: 300: the old site asked the person to wait before another try.
• 401 legacy_unavailable: the organization checks old accounts at sign-in, and the old site did not answer. The password may still be right; try again in a minute.

While the organization moves accounts from its previous website and asks that site at sign-in, a login this organization does not know, or a password that fails here, is checked there too. A password longer than 256 characters is never sent. A password that opens an old account answers 200 with legacy instead of 401: action is move with a ticket for the move page, or old_site with a url on the old site's own domain that signs the person in there, because that account still has servers there. An old username of an account that already moved to this organization signs in to that account here, with its password.

application/json (required)

POST /api/v1/orgs/{org_slug}/auth/logout

Revoke the current access token (and its refresh twin if present).

GET /api/v1/orgs/{org_slug}/auth/me

The signed-in customer.

support_session is set when the token is a support session that your team or Coritan support opened as the customer: its mode (read_only, servers or full) and expires_at. A storefront that receives a token at /auth/callback with impersonated=1 reads this to confirm it is a support session before it signs the visitor in, and shows whose account is on screen until the session ends.

Fields of a 200 response:

PATCH /api/v1/orgs/{org_slug}/auth/me

application/json (required)

Fields of a 200 response:

POST /api/v1/orgs/{org_slug}/auth/me/new-account-notice/dismiss

Hide the "this is a new account" notice for good. Refused in a support session: it is the customer's to dismiss.

GET /api/v1/orgs/{org_slug}/auth/mfa

POST /api/v1/orgs/{org_slug}/auth/mfa/disable

Turn the factor off with a current code, and with the password when the account has one. Refused while the brand requires a factor of everyone.

application/json (required)

POST /api/v1/orgs/{org_slug}/auth/mfa/enable

application/json (required)

POST /api/v1/orgs/{org_slug}/auth/mfa/recovery-codes

application/json (required)

POST /api/v1/orgs/{org_slug}/auth/mfa/setup

POST /api/v1/orgs/{org_slug}/auth/mfa/verify

application/json (required)

GET /api/v1/orgs/{org_slug}/auth/oauth/connections

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

DELETE /api/v1/orgs/{org_slug}/auth/oauth/connections/{provider}

GET /api/v1/orgs/{org_slug}/auth/oauth/providers

Public: which social providers the storefront offers.

A provider is listed when Coritan has it configured and the organization's settings do not leave it out.

Fields of a 200 response:

POST /api/v1/orgs/{org_slug}/auth/oauth/set-password

Set a first password on an account that has none, such as one made with a social account, a code or at checkout.

Needs the signed-in customer's token. The address must be proven first (email_verified in GET /auth/me): a session can exist for an address its owner has not confirmed, such as the one POST /auth/checkout-session returns, and a password chosen there would still open the account after the owner confirmed the address. 403 with detail.error email_unproven and a message to show says so. POST /auth/forgot-password emails a link that proves the address and sets the password in one step. 400 when the account already has a password, 422 for a password that is too weak. The answer is {"message": "Password set successfully"}.

application/json (required)

GET /api/v1/orgs/{org_slug}/auth/oauth/{provider}/authorize

GET /api/v1/orgs/{org_slug}/auth/oauth/{provider}/callback

Finish a provider sign-in and send the customer back to the storefront.

The provider's redirect lands here with a code. We answer 302 to the storefront's /auth/callback page with the result in the URL fragment: access_token, refresh_token and expires_in, or mfa_token and its flags, or error. new_account=true marks an account this sign-in made, and a link a signed-in customer started ends with linked=true and provider.

A provider only vouches for an address it says it checked. We make an account from a sign-in only when it did, and we never link a provider to an account the customer did not sign in to. These error values say what to tell the customer:

• account_exists_login_required: an account with this address has a password. The customer signs in with it, then connects the provider in their account settings.
• account_exists_no_password: an account with this address has no password. The customer asks for a sign-in code or a password link by email, then connects the provider in their account settings.
• email_unverified_by_provider: the provider did not say it had checked the address, so we made no account. The customer confirms the address with the provider and tries again, or signs up with email.
• no_email_from_provider: the provider shared no address.
• email_unproven: a customer tried to connect a provider to an account whose address nobody has proven. They confirm the address by email first, with a sign-in code, the confirmation link or a password link.
• provider_already_linked_to_another_account: another customer has linked this provider account.
• discord_link_limit, with retry_at: this Discord account moved between customers too often. retry_at is when it can be linked again.
• account_disabled, email_domain_blocked and customer_limit_reached: the account is not active, the address's domain is blocked, or the organization is at its customer limit.
• access_denied, invalid_state, missing_code_or_state, token_exchange_failed, no_access_token, profile_fetch_failed, provider_not_available and the rest: the sign-in did not finish, and the customer starts it again.

POST /api/v1/orgs/{org_slug}/auth/reauth/code

Email the signed-in customer a 6-digit code that confirms an action that cannot be undone, such as deleting a server or closing the account.

Needs the customer's own session. The code always goes to the address on the account, so it works for an account with no password and no linked social account, and the body is empty ({}). Send challenge and the code to POST /auth/reauth/code/verify, which answers with a reauth_token that the request needing it accepts as reauth_token.

A code works for 10 minutes and 5 tries. It counts against the same limits as a sign-in code, because both go to the same inbox: the address can ask for another after 30 seconds and gets at most 5 codes in 15 minutes, and one network at most 20 an hour.

Refusals: 401 without a session; 403 for a support session opened as the customer, and for an account that is banned, suspended or closed; 429 with Retry-After while the address or the network must wait; 503 when we cannot send your organization's email.

Fields of a 200 response:

POST /api/v1/orgs/{org_slug}/auth/reauth/code/verify

Trade the code from POST /auth/reauth/code for a reauth_token.

Needs the same customer's session. The answer is {"reauth_token", "expires_in": 300}: send the token as reauth_token with the request that needs a confirmation, within 5 minutes. A code works once.

Refusals: 400 with detail.error wrong_code, expired or used, a message to show and attempts_left. The fifth wrong code spends the challenge. A code that was sent for signing in, or to another customer, reads as expired, and so does a challenge your organization did not issue. 401 without a session; 403 for a support session; 429 with Retry-After after many wrong codes from one network.

application/json (required)

Fields of a 200 response:

POST /api/v1/orgs/{org_slug}/auth/refresh

Fields of a 200 response:

POST /api/v1/orgs/{org_slug}/auth/register

Self-service customer signup for the organization's storefront.

Send email and password; username, the names, company, phone, turnstile_token and marketing_consent are optional. We answer 201 with a session (access_token and refresh_token), or with the second-factor step when the organization asks every customer for one. The address starts unconfirmed: nothing waits for the confirmation link, and we email it.

Refusals carry a code beside the detail sentence: 409 email_taken when an account here has the address, 409 username_taken for a name that is in use, 403 email_banned for an address that cannot register again, and 403 customer_limit_reached when the organization is full. A sentence in detail stays the same for each, so older pages keep working.

While the organization moves accounts from its previous website and asks that site at sign-in, we also ask it whether the address or the username belongs to an account there. When it does, we answer 409 account_on_old_site: the person should sign in with the old username and password, and we move the account for them. When the old site does not answer, the sign-up goes ahead.

application/json (required)

POST /api/v1/orgs/{org_slug}/auth/resend-verification

Send another confirmation link to the signed-in customer's own address.

Authenticated rather than taking an email in the body: an anonymous version would let anyone post mail to any address on this org's behalf, and there is nothing to gain from it when the customer can already sign in.

POST /api/v1/orgs/{org_slug}/auth/reset-password

Set a new password with the token from a password reset email.

The token comes from the forgot-password email (it works for 2 hours), from the email that asks a customer to choose a password for an account made at checkout (3 days), from the set-password button of an account moved from a previous site (30 days) or from the new link that POST /auth/reset-password/resend sends (7 days). It works once. The reset signs the customer out everywhere, and the answer is {"message": "Password updated", "email"} with the account's address, so the page can sign the customer in with the new password straight away.

A link that names the customer carries id beside token. Send both: the token is then checked on that customer alone. Without id the token is looked up among the organization's customers, which is how links sent before id existed still work; that lookup is limited to 10 requests an hour from one network (429).

400 Invalid reset token for a token that is wrong, was replaced by a newer one or was used already, and for an id that is unknown, belongs to another organization or is not an active customer: the answer is the same for all of them. A genuine token past its time answers 400 Reset token expired; when the request carried id the detail is {"code": "reset_link_expired", "message": "Reset token expired"}, and the page can offer POST /auth/reset-password/resend for a new link.

The link went to the account's address, so using it proves the address. When nobody had proven it before, we mark it confirmed, remove an authenticator from an account that had no password (only a session nobody had vouched for can have added one), remove the sign-in links to other services that an account move carried to it, and apply invites to share a server with the address.

application/json (required)

POST /api/v1/orgs/{org_slug}/auth/reset-password/resend

Email a new password link to the customer a link was made for.

Send the id and token from the link that does not work, expired or not. When that token is one we hold for an active customer, we issue a new link that works for 7 days, replace every older link of the customer with it (only the newest link works) and email it to the address on the account. The page offers this when POST /auth/reset-password answers reset_link_expired.

The answer is always 200 {"message": "If that link was ours, we sent a new one to the address on file."}, whether or not a link went out, so it says nothing about which customers exist. When the organization cannot send email, nothing is sent and the old link stays as it was.

429 when the network has asked 20 times in an hour, or when the customer has had 3 new links in an hour. The customer's budget counts only requests with the right token, so someone who knows an id cannot use it up.

application/json (required)

GET /api/v1/orgs/{org_slug}/auth/sessions

Where this account is currently signed in.

The token row already records the address and user agent it was issued to, so a customer can see a session they do not recognise without us keeping a second log of it. Tokens are never returned, only the hash we match the caller's own session on. country_code is where the address places (see _session_countries), or null when nothing can place it, so the page can say "Germany · 203.0.113.9" rather than an address alone.

Support sessions are labelled rather than hidden. An admin looking at an account shows up here as a sign-in from an address the customer will not recognise, and the honest answer to that is to say what it is.

POST /api/v1/orgs/{org_slug}/auth/sessions/revoke-others

Sign out everywhere except here.

The one action worth having after a shared or stolen laptop, and it must not log the customer out of the browser asking for it, so the presented token is the one row left alone.

GET /api/v1/orgs/{org_slug}/auth/username-available

Whether a username can be taken at signup, and why not when it cannot.

Public, because the signup form asks while somebody is still typing and has no session yet. It gives away nothing the community pages do not: a handle is the name everyone already sees above every message its owner posts. Answers rather than raising, so a 422 per keystroke is not the shape of it.

POST /api/v1/orgs/{org_slug}/auth/verify-email

Confirm an address from an emailed link.

Public, because the customer may follow the link in a browser that is not signed in. The token is the credential. The first time an address is confirmed, every session the account had before ends, such as one a checkout handed to a stranger, and invites to share a server with the address now apply (settle_first_proof). Following the link again changes nothing. The answer is {"verified": true, "email"}; 400 for a link that is not valid, has expired or was sent to another address.

application/json (required)