Auth

Every app has its own users, in its own database, separate from your Authoric console account. They sign up and sign in against your app's routes (/{appUid}/auth/...) and get tokens that work for that app and nothing else. This page covers the model and the two calls every app makes first: sign up, and sign in.

The model in one paragraph

A user is a row in your app's users table, addressed by its uid. Every user belongs to at least one of your app's organizations, and a session always acts in exactly one of them, the active organization. Signing in, by any method, ends at the same session issuer, which decides the active organization, checks two-factor authentication, and returns the same payload. What a signed-in user may then do is decided by the policies on their roles, evaluated on every request.

Sign up

POST /{appUid}/auth/signup creates a user and a new organization of their own, makes them its owner, and signs them in.

curl -X POST "$AUTHORIC_URL/$APP_UID/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dana@example.com",
    "password": "Str0ng!Passphrase",
    "fname": "Dana",
    "lname": "Reyes"
  }'

Sign-up also emails a "confirm your email" link to the address. Pass verifyRedirectTo, a page of yours on an allowed domain, to have the link open there; The user's own account covers confirming. When your app requires a confirmed address before anyone signs in, sign-up answers { "verificationRequired": true, "email": "..." } instead, with no tokens.

The password must be at least 8 characters with an uppercase letter, a lowercase letter, a number and a special character. Unknown fields are refused, including any attempt to name an existing organization: sign-up never joins someone else's organization. To bring a person into an existing organization, invite them.

Sign in

POST /{appUid}/auth/login takes an email and password. Sign-in methods covers the passwordless and social doors; they all return the same payload.

curl -X POST "$AUTHORIC_URL/$APP_UID/auth/login" \
  -H "Content-Type: application/json" \
  -d '{ "email": "dana@example.com", "password": "Str0ng!Passphrase" }'

A wrong email, a wrong password, an account with no password, and a password the user switched off all answer the same 401 Invalid email or password, in the same time, so the response never reveals which addresses have accounts.

What comes back

{
  "uid": "0199a3c2-5b1e-7c4d-9f2a-3e8b6d1c0a47",
  "email": "dana@example.com",
  "fname": "Dana",
  "lname": "Reyes",
  "status": "active",
  "created_at": "2026-10-02T14:11:09.000Z",
  "updated_at": "2026-10-02T14:11:09.000Z",
  "org": { "uid": "0199a3c2-5b1d-74e0-8c55-1f0e2a9b7d31", "name": "Dana Reyes" },
  "orgUid": "0199a3c2-5b1d-74e0-8c55-1f0e2a9b7d31",
  "activeOrgUid": "0199a3c2-5b1d-74e0-8c55-1f0e2a9b7d31",
  "subjectType": "user",
  "auth": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "activeOrgUid": "0199a3c2-5b1d-74e0-8c55-1f0e2a9b7d31"
  }
}

The account is an allow-list projection: no internal ids, no password hash. Two shapes replace it in specific cases, and a client should check for them before reaching for auth:

Calling your API

Send the access token as a bearer token on every request:

Authorization: Bearer <access token>

Access tokens last 15 minutes. Exchange the refresh token at POST /{appUid}/auth/token for a new pair before then. Refresh tokens are single-use, so store both new tokens every time and run only one refresh at once. Sessions & token refresh has the full client strategy.

Treat both tokens as opaque. Authoric holds the signing key and checks every request, including whether the session is still live, so there is nothing for your backend to verify locally: forward the token and act on the response.

The active organization lives in the token

A token states who the user is and which organization they are acting in. Both are set when the session is issued and when it is refreshed, and no query parameter or body field on an ordinary request can change them.

• A user with one organization is signed into it.
• A user with several is signed into their own (the one created at sign-up) unless the sign-in names another with activeOrgUid.
• To switch, refresh with activeOrgUid. The server checks the membership first, and also checks the target organization's two-factor requirement, so switching cannot step around it.

Errors you will meet here

The error body is { "error": { "error": "<message>", "code": "<CODE>", "details": {...} }, "requestId": "..." }. Branch on error.code where there is one.

A request that fails validation (a missing field, a weak password) answers 400 VALIDATION_ERROR, with the field in details.field and the reason in the message.

What's next