Docs Guide

Build identity the right way.

Account creation, login methods, session checks, OAuth 2.0 flows, permissions and agent IAM. Plain HTTPS and fetch, no vendor SDK.

OAuth quickstartProtect an app in three requests. Verify sessionsOne call from your backend.

01Getting started

Create a Towly account once and use it everywhere. Registration and sign-in run through the Towly login UI, so you never handle passwords yourself.

Register at id.towly.ai/registration with an email address, and sign in any time at id.towly.ai/login. The session is a secure, HttpOnly cookie on .towly.ai. Verify it in code by calling the whoami endpoint from your backend (section 03).

02Login options

Every account supports several sign-in methods. All of them produce the same session.

Password	12-character minimum with breach-list checks.
Passkey	Device-bound WebAuthn credentials, phishing resistant.
Email code	Passwordless one-time code sent to the account email.
TOTP app	Time-based codes as a second factor for step-up.
Security keys	Hardware WebAuthn keys for the strongest protection.
Recovery codes	One-time fallback codes.

Social sign-in is not a platform login method yet. Tenants can connect their own social and enterprise providers under Federation in the console.

03Session verification

Forward the session cookie to whoami. A 200 means the session is valid; a 401 means it is not.

const res = await fetch("https://auth.towly.ai/sessions/whoami", { credentials: "include" });
if (!res.ok) {
  window.location = "https://id.towly.ai/login"; // 401: no valid session
  throw new Error("unauthenticated");
}
const session = await res.json();
// session.identity.traits.email, session.authenticator_assurance_level (aal1 | aal2)

04OAuth 2.0 and OIDC

Towly is a full OAuth 2.0 authorization server at api.towly.ai.

Authorize	Redirect to `/oauth2/auth` with `client_id`, `redirect_uri`, `response_type=code` and `scope`.
Login and consent	The user signs in if needed and approves the requested scopes at `consent.towly.ai`.
Token exchange	Trade the code at `/oauth2/token` for access and ID tokens.

const res = await fetch("https://api.towly.ai/oauth2/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code,
    redirect_uri: "https://yourapp.example/callback",
    client_id: "your-client-id",
  }),
});
const { access_token, id_token } = await res.json();

Discovery metadata, including token and JWKS URLs, is at api.towly.ai/.well-known/openid-configuration.

05Relationship-based permissions

Model your domain as relations such as document:report#viewer@user:ana, then ask one question per request.

const res = await fetch(
  "https://auth.towly.ai/relation-tuples/check?namespace=document" +
  "&object=report&relation=viewer&subject_id=ana",
  { headers: { Authorization: `Bearer ${apiToken}` } }
);
const { allowed } = await res.json(); // false: respond 403

07Management console

Prefer a UI? app.towly.ai is your control plane: identities and sessions, OAuth 2.0 clients, permission relations, credential rotation and agent activity. Sign in with the account from section 01.

Open the console

08Endpoint reference

`auth.towly.ai`	Identity API: registration, login flows, sessions, permissions
`id.towly.ai`	Login UI: sign up, sign in, settings, recovery, verification
`app.towly.ai`	Console: identities, clients, permissions, audit