HTTP API and errors

Every SDK is a thin layer over this JSON API, so any language can use it directly. Base URL: https://tausi-auth.onrender.com/api/v1. The repository's docs/API.md describes each endpoint's body and response.

Requests and responses

curlShell

# Sign in (publishable key)
curl -X POST https://tausi-auth.onrender.com/api/v1/auth/sign-in/email \
  -H "X-Tausi-Key: pk_…" -H "Content-Type: application/json" \
  -d '{"email":"asha@example.com","password":"…"}'
# → { "data": { "user": {…}, "session": {…}, "sessionToken": "…" }, "requestId": "…" }

# Verify that token from your backend (secret key)
curl -X POST https://tausi-auth.onrender.com/api/v1/backend/sessions/verify \
  -H "Authorization: Bearer sk_…" -H "Content-Type: application/json" \
  -d '{"sessionToken":"…"}'
# → { "data": { "valid": true, "user": {…}, "session": {…} } }

Successful responses are { "data": …, "requestId" }; errors are { "error": { "code", "message", "details"? }, "requestId" }.
End-user calls send X-Tausi-Key: pk_…, plus Authorization: Bearer <sessionToken> when signed in.
When a response has an X-Tausi-Session-Token header, the token was renewed: store the new one.
Apps that limit accounts per device send a stable per-install X-Tausi-Device ID.
With bot protection on, sign-up / sign-in / forgot-password send the Turnstile or hCaptcha token in X-Tausi-Captcha.

End-user API (publishable key)

GET	`/api/v1/auth/providers`
POST	`/api/v1/auth/sign-up/email`
POST	`/api/v1/auth/sign-in/email`
POST	`/api/v1/auth/sign-out`
GET	`/api/v1/auth/session`
POST	`/api/v1/auth/change-password`
POST	`/api/v1/auth/forgot-password`
POST	`/api/v1/auth/reset-password`
POST	`/api/v1/auth/send-verification-email`
POST	`/api/v1/auth/verify-email`
GET	`/api/v1/auth/sessions`
DELETE	`/api/v1/auth/sessions/:id`
DELETE	`/api/v1/auth/sessions`
GET	`/api/v1/users/me`
PATCH	`/api/v1/users/me`
DELETE	`/api/v1/users/me`
POST	`/api/v1/auth/two-factor/verify`
POST	`/api/v1/auth/two-factor/setup`
POST	`/api/v1/auth/two-factor/enable`
POST	`/api/v1/auth/two-factor/disable`
POST	`/api/v1/auth/two-factor/backup-codes`
POST	`/api/v1/auth/oauth/exchange`
POST	`/api/v1/auth/token`

Backend API (secret key)

Server-to-server only, with Authorization: Bearer sk_…. Confined to the key's project.

POST	`/api/v1/backend/sessions/verify`
GET	`/api/v1/backend/project`
GET	`/api/v1/backend/users`
GET	`/api/v1/backend/users/:id`
PATCH	`/api/v1/backend/users/:id`
DELETE	`/api/v1/backend/users/:id`
POST	`/api/v1/backend/users/bulk`
POST	`/api/v1/backend/users/:id/ban`
DELETE	`/api/v1/backend/users/:id/ban`
POST	`/api/v1/backend/users/:id/suspend`
DELETE	`/api/v1/backend/users/:id/suspend`
DELETE	`/api/v1/backend/users/:id/two-factor`
POST	`/api/v1/backend/users/:id/revoke-sessions`
GET	`/api/v1/backend/sessions`
POST	`/api/v1/backend/tokens`

Error codes

Branch on code; messages may change. Quote the requestId when reporting a problem.

Code	Status	Meaning
`VALIDATION_ERROR`	400	Body or query failed validation; details.issues lists each field and its problem.
`INVALID_CREDENTIALS`	401	Wrong email or password (also for unknown emails, and for blocked users with a wrong password).
`UNAUTHENTICATED`	401	Missing, expired or revoked session. SDKs clear the stored token.
`INVALID_KEY`	401	Unknown publishable key, or a bad or revoked secret key.
`INVALID_PASSWORD`	400	The current password (change password, delete account) is wrong.
`EMAIL_NOT_VERIFIED`	403	Password was right but the email isn't verified yet.
`ACCOUNT_BANNED`	403	The user is banned. Only after a correct password.
`ACCOUNT_SUSPENDED`	403	The user is suspended; details.suspendedUntil says until when.
`ORIGIN_NOT_ALLOWED`	403	Browser origin isn't in the project's allowed origins.
`SIGNUP_LIMITED`	403	Too many accounts from this network or device (project abuse limits).
`ACCESS_BLOCKED`	403	The client's IP is on the project's blocklist.
`CAPTCHA_REQUIRED`	400	The project protects this action with a bot check; send the widget's token in X-Tausi-Captcha. details has provider and siteKey.
`CAPTCHA_INVALID`	400	The bot-check token was rejected or expired. Show the widget again.
`PASSWORD_BREACHED`	400	The password appears in a known data breach (Have I Been Pwned). Ask for a different one.
`TWO_FACTOR_REQUIRED`	403	Dashboard step-up on an account with two-factor on: send the authenticator code too. (Sign-in itself answers 200 with twoFactorRequired; Python, PHP and Flutter raise it as an exception.)
`INVALID_TWO_FACTOR_CODE`	400	Wrong authenticator or backup code. 5 tries per sign-in; after 10 the factor locks for 15 minutes.
`TWO_FACTOR_LOCKED`	429	10 wrong two-factor codes in a row: the factor is locked for 15 minutes.
`TWO_FACTOR_CHALLENGE_EXPIRED`	401	The two-factor sign-in step took longer than 5 minutes, or the twoFactorToken is invalid. Sign in again.
`REDIRECT_NOT_ALLOWED`	400	redirectTo isn't one of the project's allowed origins or redirect URLs.
`INVALID_TOKEN`	400	Verification, reset or sign-in code expired or already used.
`NOT_FOUND`	404	Unknown route, or a resource you don't own.
`EMAIL_ALREADY_REGISTERED`	409	Sign-up with an email that has an account. Its owner has been emailed.
`USERNAME_TAKEN`	409	Another user in the project has that username.
`CONFLICT`	409	A limit was reached, or the action conflicts with existing data.
`RATE_LIMITED`	429	Too many attempts; wait for the Retry-After header (retryAfter in SDKs).
`NETWORK_ERROR / TIMEOUT`	—	SDK only: Tausi couldn't be reached.