Xinference Docs
Get started

Authentication

Xinference authenticates requests with an HttpOnly session cookie. You obtain a session by signing up or signing in with email and password, or via Google SSO. Once signed in, the browser (or HTTP client) automatically sends the session cookie on subsequent requests — there is no API-key or Bearer-token scheme on the platform API.

All authentication routes are mounted under /v1.

Sign Up

POST /v1/user/register

Request body:

{
  "email": "you@example.com",
  "password": "your-password",
  "organization": "Acme Corp",
  "first_name": "Alice",
  "last_name": "Doe",
  "country": "US",
  "contact_number": "+1-555-0100"
}
Field Type Required Notes
email string Yes 3–320 chars
password string Yes 8–72 bytes
organization string Yes 1–255 chars
name / first_name / last_name string No Optional profile fields
country / contact_number string No Optional profile fields

On success the response sets the session cookie and returns the authenticated session.

Sign In

POST /v1/user/signin

Request body:

{
  "email": "you@example.com",
  "password": "your-password"
}

Returns the authenticated session and sets the session cookie. Invalid credentials respond 401 with "Invalid email or password."

Response shape (register, sign-in, and session):

{
  "authenticated": true,
  "user": {
    "id": 42,
    "email": "you@example.com",
    "name": "Alice Doe",
    "organization": "Acme Corp",
    "role": { "id": 1, "name": "super_admin" },
    "requires_profile_completion": false
  },
  "session": {
    "expires_at": "2025-06-24T10:00:00Z",
    "auth_method": "password"
  }
}

Current Session & Sign Out

GET /v1/auth/session
PATCH /v1/user/profile
POST /v1/user/logout
  • GET /v1/auth/session — returns the current authenticated session (same shape as above).
  • PATCH /v1/user/profile — update the signed-in user's profile; returns the refreshed session.
  • POST /v1/user/logout — clears the session; returns { "authenticated": false }.

Google SSO

GET /v1/sso/providers
GET /v1/sso/login/google
GET /v1/sso/callback/google
  • GET /v1/sso/providers — lists the configured SSO providers. When Google OIDC is configured it returns { "providers": [{ "name": "google", "display_name": "Google", "configured": true, "login_url": "/v1/sso/login/google" }] }.
  • GET /v1/sso/login/google — begins the Google sign-in flow (redirect to Google).
  • GET /v1/sso/callback/google — completes the flow and establishes a session (auth_method: "google").

Google SSO is available only when the server is configured with GOOGLE_OIDC_CLIENT_ID, GOOGLE_OIDC_CLIENT_SECRET, and the related OIDC settings.

Password Reset

POST /v1/auth/password-reset/request
POST /v1/auth/password-reset/confirm
  • POST /v1/auth/password-reset/request — body { "email": "you@example.com" }. Always responds { "accepted": true } (it does not reveal whether the email exists) and emails a reset link if the account exists.
  • POST /v1/auth/password-reset/confirm — body { "token": "...", "password": "new-password" }. Responds { "reset": true } on success.

Security Notes

  • The session cookie is HttpOnly. Its name is configurable via SESSION_COOKIE_NAME.
  • CSRF protection is enforced on state-changing requests.
  • For self-hosted deployments, set SESSION_COOKIE_SECURE and SESSION_COOKIE_SAMESITE appropriately for your environment. See Environment Variables →.