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. The management API (deployments, organization, billing, etc.) accepts the session cookie only; the inference endpoints additionally accept an API key as a Bearer token.

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"
}

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.

API Keys

API keys provide programmatic access to the inference endpoints (/v1/chat/completions and /v1/embeddings). A key is sent as Authorization: Bearer xi-sk-…. Each key belongs to your organization, and is scoped to one or more specific deployments. Managing API keys requires the admin or super_admin role. Keys are managed under /v1/organization/api-keys:

GET    /v1/organization/api-keys
POST   /v1/organization/api-keys
GET    /v1/organization/api-keys/deployment-options
PATCH  /v1/organization/api-keys/{api_key_id}
DELETE /v1/organization/api-keys/{api_key_id}

Create a key with a name and the deployments it may access:

{
  "name": "production-app",
  "deployment_ids": ["dep_abc123"],
  "expires_at": null
}

The create response returns the secret once as key (store it securely), along with the key record:

{
  "key": "xi-sk-...",
  "api_key": {
    "id": 1,
    "organization_id": 1,
    "name": "production-app",
    "key_prefix": "xi-sk-...",
    "status": "active",
    "expires_at": null,
    "last_used_at": null,
    "revoked_at": null,
    "deployments": [ { "id": "dep_abc123", "model_name": "qwen2.5-instruct", "status": "running" } ]
  }
}

• GET /deployment-options lists the deployments a key can be scoped to.
• PATCH /{api_key_id} updates a key's name, allowed deployments, expiry, or status.
• DELETE /{api_key_id} revokes a key (status becomes revoked); revoked keys cannot be updated.

Security Notes

• The session cookie is HttpOnly. Its name is configurable via SESSION_COOKIE_NAME.
• API keys are shown in full only at creation time; afterward only the key_prefix is returned.
• CSRF protection is enforced on state-changing requests. The management endpoints reject Authorization headers (use the session cookie); the Bearer API key is for the inference endpoints.
• For self-hosted deployments, set SESSION_COOKIE_SECURE and SESSION_COOKIE_SAMESITE appropriately for your environment. See Environment Variables →.