Authentication

​

Auth Modes

​

Login Flows

​

otp

1. Client posts email to POST /auth/login
2. Sinas sends a 6-digit code (valid 10 min by default)
3. Client posts code to POST /auth/verify-otp and receives access + refresh tokens

​

password

1. Client posts email + password to POST /auth/login
2. Sinas verifies and immediately returns access + refresh tokens

​

password+otp

1. Client posts email + password to POST /auth/login
2. On password match, Sinas sends a 6-digit OTP and returns an OTP session id
3. Client posts code to POST /auth/verify-otp and receives access + refresh tokens

​

Tokens

• Access token — short-lived (default 15 min), sent as Authorization: Bearer <token>
• Refresh token — long-lived (default 30 days), exchanged at POST /auth/refresh

POST   /auth/login                # Start login (mode-dependent payload)
POST   /auth/verify-otp           # Verify OTP for otp / password+otp modes
POST   /auth/refresh              # Get new access token
POST   /auth/logout               # Revoke refresh token
GET    /auth/me                   # Get current user info

​

Superadmin Bootstrap

• SUPERADMIN_EMAIL — email of the user to create / promote to Admins
• SUPERADMIN_PASSWORD — only used when AUTH_MODE is password or password+otp. Setting this on a running deployment and restarting the backend will reset the password — the escape hatch for “admin lost their password.”

​

Password Reset

• User-initiated — not implemented when AUTH_MODE=password (no email channel guaranteed). Use admin reset.
• Admin-initiated — an admin generates a one-time reset link from the user management page in the console and delivers it out-of-band (Slack, in person).
• Lost-superadmin escape hatch — set SUPERADMIN_PASSWORD in the env and restart the backend.

​

API Keys

POST   /api/v1/api-keys           # Create key (plaintext returned once)
GET    /api/v1/api-keys           # List keys
GET    /api/v1/api-keys/{id}      # Get key details
DELETE /api/v1/api-keys/{id}      # Revoke key

​

Token Exchange (bring your own auth)

1. An admin links your application’s user ids to Sinas users as external identities — or you let the exchange auto-provision them.
2. Your backend calls the exchange endpoint with an API key holding the sinas.auth.exchange:all permission:

POST /auth/token/exchange
X-API-Key: <exchange key>
{
  "provider": "acme-app",
  "subject": "usr_8f3a2",
  "email": "jane@acme.com",
  "metadata": {"name": "Jane"},
  "custom_fields": {"plan": "enterprise"},
  "auto_provision": true
}

3. The response contains a normal Sinas access + refresh token pair for that user, which your frontend uses against the runtime API. All ownership scoping (:own), permissions, and audit logging apply as if the user had logged in directly.

• The user is resolved by (provider, subject). If unknown and email is given, an existing user with that email is matched and the identity is linked to them.
• With auto_provision: true, unknown users are created and assigned the TOKEN_EXCHANGE_DEFAULT_ROLE (default GuestUsers). email is required to provision.
• metadata is stored on the identity and refreshed on every exchange. custom_fields is shallow-merged into the user’s custom fields (partner keys win, admin-set keys survive).
• provisioned: true in the response indicates the exchange created the user.