Authentication¶
How callers prove who they are. Read this first; the other guides assume you can obtain a session.
What exists today¶
| Credential | Used for | Where it works |
|---|---|---|
| Session cookie | A person acting in a tenant, through the web app or a script that signs in as them | Tenant GraphQL (POST /api/graphql) |
| Shopify session token | A shopper's checkout extension asking for a refund estimate | Checkout GraphQL only (see Checkout API) |
There is no API key yet. No machine credential can be created for a tenant. Today every request to the tenant API uses a signed-in session, so an integration that must run unattended has to sign in as a user and keep that user's session alive. Tenant API keys are planned; nothing in this guide depends on them.
One consequence: the shipping label PDF download (GET /api/shipping-labels/:labelId/document) refuses sessions, and no
other credential is available to integrators, so label PDFs cannot be downloaded with a session today.
Authentication is Better Auth: email and password, with cookies. Its endpoints live
under /api/auth/. The examples use API for the base URL of your ecomtaxfree host:
API=https://<your ecomtaxfree host>
Sign up from an invitation¶
Accounts exist only by invitation. A tenant owner or admin invites you (see Tenants and members), and the invitation email contains a link of this shape:
https://<host>/sign-in?invitationId=<invitationId>&mode=sign-up#inviteToken=<inviteToken>
Sign-up succeeds only when the request carries both values, the invitation is pending and unexpired (invitations last 7 days by default), and it is addressed to exactly the email you sign up with (compared in lowercase).
curl -sS -X POST "$API/api/auth/sign-up/email" \
-H 'content-type: application/json' \
-H "origin: $API" \
-d '{
"email": "[email protected]",
"name": "New Person",
"password": "a-long-password",
"invitationId": "<invitationId>",
"inviteToken": "<inviteToken>"
}'
- The
inviteTokentravels in the link's fragment (#inviteToken=), so browsers never send it to a server. Only the invited inbox holds it; the API never returns it. - Malformed input (an invalid email, a password that is too short) answers 400 before anything else is checked.
- Otherwise any failure answers the same 403 whether or not the invitation exists, so a probe learns nothing. The one exception: an email that already has an account answers 422 first. Sign in instead.
- A new account starts with a verified email, because the token proves the inbox was read.
- After signing up, accept the invitation to join the tenant (see Tenants and members).
Sign in¶
curl -sS -c cookies.txt -X POST "$API/api/auth/sign-in/email" \
-H 'content-type: application/json' \
-H "origin: $API" \
-d '{"email": "[email protected]", "password": "<your password>"}'
A 200 response sets the session cookies; the -c flag stores them. Send them back with -b cookies.txt on later
requests.
Two details worth knowing:
- Send an
Originheader with the web app's origin. Better Auth checks the origin of requests that carry cookies, and refuses origins it does not trust. Sign-in itself may pass without one, butset-active,invite-member,accept-invitationandsign-outwill not, so a server-side client should always send it. - A session may have no tenant until you choose one. Until then, tenant requests answer
TENANT_REQUIRED. See Tenants and members.
Check that a session is live:
curl -sS -b cookies.txt "$API/api/auth/get-session"
The answer holds the user and a session whose activeOrganizationId is the tenant the session currently acts in (or
null).
Sign out¶
curl -sS -b cookies.txt -X POST "$API/api/auth/sign-out" \
-H 'content-type: application/json' -H "origin: $API" -d '{}'
Two-factor authentication¶
Two-factor (TOTP with backup codes) is optional. If you enrol:
POST /api/auth/two-factor/enablewith{ "password": "..." }answers atotpURIand backup codes.POST /api/auth/two-factor/verify-totpwith{ "code": "123456" }confirms the authenticator, and ends your other sessions.
From then on, password sign-in answers twoFactorRedirect: true instead of a session. Finish with
POST /api/auth/two-factor/verify-totp ({ "code": ... }) or POST /api/auth/two-factor/verify-backup-code. Trusting
a device is refused (400 TRUST_DEVICE_REFUSED): every sign-in needs a code.
Password reset¶
The password reset endpoints (request-password-reset and reset-password) currently answer 404. There is no
self-service reset yet.
Authentication errors¶
Errors arrive as GraphQL errors with a code in extensions.code; see GraphQL API for the
shape.
| Code | Meaning |
|---|---|
UNAUTHENTICATED |
No credential, an unknown or tampered cookie, or a signed-out session |
TENANT_REQUIRED |
The session has no active tenant, or it is no longer a member of it |
TENANT_MISMATCH |
x-tenant-id names a tenant other than the session's active one |
FORBIDDEN |
The credential is valid but its role or retailer access does not allow this |
SERVICE_UNAVAILABLE |
Identity verification itself is down; retry later, this is not a denial |