Skip to content

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 inviteToken travels 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 Origin header 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, but set-active, invite-member, accept-invitation and sign-out will 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:

  1. POST /api/auth/two-factor/enable with { "password": "..." } answers a totpURI and backup codes.
  2. POST /api/auth/two-factor/verify-totp with { "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