Documentation

How it works

Every app you build is a project in Tausi. A project has its own users (the same email in two projects is two separate accounts), its own settings, and two kinds of key:

The flow is always the same:

1. Your app signs the user in with the publishable key and gets a session token.
2. It sends that token to your API as Authorization: Bearer <token>.
3. Your API checks it with the secret key. Tausi answers with the user, or "not valid" if the token is expired, revoked, or the user is banned or suspended.

Set up a project

1. Create a project from Projects. Give it your app's name and its URL.
2. Allowed origins (project Settings): every web origin your app runs on, such as https://app.example.com and http://localhost:3000. Browser requests and social sign-in redirects are only accepted from these.
3. App URL: where your app lives. By default, verification and password-reset emails link to <App URL>/verify-email?token=… and <App URL>/reset-password?token=…. Your app can choose another page per request with redirectTo; see Email links.
4. Copy the keys from API keys. The secret key is shown once; you can create more and revoke old ones.
5. Optional: turn on Google, GitHub, Apple and others under Social sign-in, and set password rules and abuse limits under Security.

Store the keys as environment variables. Every guide uses these names:

TAUSI_URL=https://tausi-auth.onrender.com
TAUSI_PUBLISHABLE_KEY=pk_…
TAUSI_SECRET_KEY=sk_…        # server only

Each project's Quickstart tab has ready-to-paste snippets with that project's real publishable key.

Email links and redirect URLs

Like Supabase's emailRedirectTo, your app can say where each email should send the user. Pass redirectTo when signing up, resending a verification email or asking for a password reset:

await tausi.signUp({ name, email, password, redirectTo: "https://app.example.com/welcome" });
await tausi.sendVerificationEmail(email, { redirectTo: "https://app.example.com/welcome" });
await tausi.forgotPassword(email, { redirectTo: "myapp://auth/reset" });   // a mobile deep link

The link in the email is your URL plus the token, keeping your own query string:

https://app.example.com/welcome?token=…&type=email_verification
myapp://auth/reset?token=…&type=password_reset

That page reads token (and type, if one page handles both) and calls verifyEmail(token) or resetPassword(token, newPassword). Redeem the token on a click rather than on page load, so email link scanners can't use it up.

Which URLs are accepted

Add entries under project Settings → Redirect URLs, one per line. * matches one host label or path segment and ** matches anything, e.g. https://*.preview.example.com/auth/** for preview deployments. javascript:, data: and a bare * host are never allowed.

Protecting accounts

Each project's Settings and Security tabs control how hard it is to abuse your sign-up and sign-in:

Adding the bot check

const captcha = await tausi.getCaptchaConfig();   // { provider: "turnstile", siteKey, actions } or null
// Render the provider's widget with captcha.siteKey (e.g. <div class="cf-turnstile" data-sitekey="…">),
// then pass the token it produces:
await tausi.signUp({ name, email, password, captchaToken: turnstileToken });
await tausi.signIn({ email, password, captchaToken });          // only if "sign_in" is in captcha.actions
await tausi.forgotPassword(email, { captchaToken });

Python: captcha_token=; PHP: the last argument $captchaToken; Flutter: captchaToken:. Over plain HTTP, send it as the X-Tausi-Captcha header.

Secret keys

Create one key per service under API keys. A key can be read-only (verify sessions and read users) and can be limited to your servers' IP addresses. Each key is rate-limited, and the first use from a new IP is logged as security.secret_key_new_ip.

Platforms

Install

Each platform page shows the command for every package manager (npm, pnpm, yarn, bun; pip, uv, poetry). You can mix SDKs: a Flutter app and a Next.js site can share one project, with a Python or PHP API checking the same tokens.

The user object

Every SDK returns the same user. Optional attributes can be set at sign-up or edited by the user; metadata is written by your backend.

{
  "id": "3021ZWj6Mx4xIfoxX9JHkC4Ph1M4ZNLQ",
  "email": "asha@example.com",          "emailVerified": true,
  "name": "Asha Mwangi",                "firstName": "Asha", "lastName": "Mwangi",
  "username": "asha",                   "image": null,
  "phoneNumber": "+255712345678",       "phoneNumberVerified": false,
  "locale": "sw-TZ",                    "timezone": "Africa/Dar_es_Salaam",
  "role": "user",                       "publicMetadata": { "plan": "pro" },
  "lastSignInAt": "2026-11-03T09:12:00.000Z",
  "createdAt": "…", "updatedAt": "…"
}

With the secret key you also get privateMetadata, status (signed_in / signed_out), activeSessions, lastActiveAt, lastSignOutAt, signInCount and access (active, suspended or banned). See Managing users.

Next steps

• Errors have a stable code in every SDK. Branch on it, not on the message: error codes.
• Everything the SDKs do is plain HTTP, so any language works: HTTP API.
• Each SDK's README in the repository (sdks/) lists every method.