Authentication

Sevah separates human-user access from registered-device access. Use only the credential type shown for an operation in the API reference.

Integration identity	Credential	Used for
Human user	sevah_session secure cookie	Organization-scoped /api/v1/* operations
Registered device	Bearer token	Device-scoped operations

Credentials are scoped and are not interchangeable.

User sessions

User authentication has two steps:

1. The approved Sevah sign-in flow produces a Firebase ID token.
2. POST /api/auth/login verifies that token and sets a Sevah session cookie.

POST /api/auth/login HTTP/1.1
Host: app.sevah.ai
Content-Type: application/json

{"id_token":"FIREBASE_ID_TOKEN"}

The cookie is HttpOnly, so browser JavaScript cannot read it. Compatible clients should use a cookie jar and send the cookie only over HTTPS to app.sevah.ai.

Use GET /api/auth/me immediately after login to verify the active user, organization, and role. A 401 Unauthorized response means the session is missing, invalid, or expired.

Refresh changed access

If an administrator changes the user's organization or role, call:

POST /api/auth/refresh HTTP/1.1
Host: app.sevah.ai
Cookie: sevah_session=SESSION_COOKIE

The server rereads the current account and reissues the session cookie. Validate the returned user context before continuing.

Log out

POST /api/auth/logout clears the server-issued cookie. Clients should also discard any locally retained copy.

Device bearer tokens

Only registered devices should call POST /auth/device. Submit the canonical device identifier and the device's declared runtime information:

POST /auth/device HTTP/1.1
Host: app.sevah.ai
Content-Type: application/json

{
  "device_id": "REGISTERED_DEVICE_ID",
  "model": "DEVICE_MODEL",
  "provider": "openai"
}

The response includes a short-lived bearer token and its expiration. Cache it securely and refresh it before expiration according to your Sevah device-integration agreement.

Send the token only on device-scoped operations that require bearer authentication:

Authorization: Bearer DEVICE_TOKEN

Never send a device token as a session cookie, and never use a user's session cookie as a device credential.

Credential handling

• Send credentials only to https://app.sevah.ai.
• Keep tokens and cookies out of URLs, logs, analytics, and error reports.
• Store retained credentials in a platform-provided secret store.
• Reject unexpected organization or role values instead of continuing with a privileged workflow.
• On 401, obtain a new credential once; do not retry indefinitely with the same credential.