Authentication

​

Authentication methods

​

How sessions work

• The session cookie is secure and not accessible to client-side JavaScript.
• Sessions are scoped to a specific tenant. To switch tenants, refresh the token via the /auth/uat endpoint.

​

Email/password authentication

​

Sign-up flow

1. Verify email — Call POST /auth/pw/email_verification with the user’s email. They’ll receive a verification token.
2. Create account — Call POST /auth/pw/user with the verification token and their chosen password.

​

Sign-in

curl -X POST https://your-instance.example.com/api/v1/auth/pw/signin \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "their-password"}'

​

Password reset

• Authenticated reset — A signed-in user calls POST /auth/pw/reset with their current and new password.
• Forgot password — Call POST /auth/pw/send_reset_email, then POST /auth/pw/reset_with_token with the emailed token.

​

SSO (Google and Tenant providers)

​

SSO flow

1. Initiate — Call POST /auth/sso/initiate with the provider type. The response includes an authorization URL.
2. Redirect — Redirect the user to the authorization URL. They authenticate with their identity provider.
3. Callback — The provider redirects back to your application. The callback endpoint (GET /auth/sso/oauth2/callback) exchanges the authorization code for a session and sets the ks_uat cookie.

​

Tenant switching

curl -X POST https://your-instance.example.com/api/v1/auth/uat \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"tenant_id": "target-tenant-id"}'

​

Signing out

curl -X POST https://your-instance.example.com/api/v1/auth/signout \
  -b cookies.txt

​

API reference