Login & Tokens

Authenticate users with email and password, manage access and refresh tokens, and discover available Sphere services. All authentication flows return JWT Bearer tokens with a default expiration of 3600 seconds.

The token response model

Every successful authentication returns a token set alongside metadata about available services.

Properties

Name
access_token
Type
string
Description
JWT access token used to authenticate subsequent API requests. Include it in the Authorization: Bearer header.
Name
refresh_token
Type
string
Description
Opaque token used to obtain a new access token when the current one expires. Store it securely on the client.
Name
token_type
Type
string
Description
Always "Bearer".
Name
expires_in
Type
integer
Description
Token lifetime in seconds. Default is 3600 (1 hour).

POST/auth/api/v1/auth/login

Authenticate a user with their login (email) and password. On success, returns a token set and a meta.services object containing the discovery URLs for all available Sphere engines. This is the primary entry point for client applications.

If the user has MFA enabled, this endpoint returns a 202 response with an mfa_token instead of a full token set. The client must then complete the MFA challenge via the MFA verify endpoint.

Required attributes

Name
login
Type
string
Description
The user's email address used as their login identifier.
Name
password
Type
string
Description
The user's password.

Request

POST

/auth/api/v1/auth/login

curl -X POST https://your-sphere.example.com/auth/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "login": "admin@acme.local",
    "password": "SecurePass123!"
  }'

Response

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "def50200a1b2c3d4e5f6...",
    "token_type": "Bearer",
    "expires_in": 3600
  },
  "meta": {
    "services": {
      "auth": "https://your-sphere.example.com/auth",
      "core": "https://your-sphere.example.com/core",
      "chat": "https://your-sphere.example.com/chat",
      "voip": "https://your-sphere.example.com/voip",
      "drive": "https://your-sphere.example.com/drive",
      "activity": "https://your-sphere.example.com/activity",
      "usermanager": "https://your-sphere.example.com/usermanager",
      "notes": "https://your-sphere.example.com/notes",
      "mail": "https://your-sphere.example.com/mail"
    }
  }
}

POST/auth/api/v1/auth/login

When a user has MFA enabled, the login endpoint returns a 202 status with an mfa_token and the list of available MFA methods. The client must present the appropriate MFA challenge and then call the MFA verify endpoint to complete authentication.

Response (202 - MFA required)

{
  "data": {
    "mfa_token": "mfa_abc123def456...",
    "methods": ["totp", "webauthn", "otp"]
  },
  "message": "MFA verification required."
}

POST/auth/api/v1/auth/refresh

Refresh token

Exchange a valid refresh token for a new token set. The previous refresh token is revoked and a new one is issued. Use this to maintain user sessions without requiring re-authentication.

Required attributes

Name
refresh_token
Type
string
Description
The refresh token obtained from the login or a previous refresh call.

Request

POST

/auth/api/v1/auth/refresh

curl -X POST https://your-sphere.example.com/auth/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "def50200a1b2c3d4e5f6..."
  }'

Response

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "def50200f6e5d4c3b2a1...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

POST/auth/api/v1/auth/logout

Logout

Revoke the current access token and its associated refresh token. After calling this endpoint, both tokens are invalidated and can no longer be used.

This endpoint requires authentication and accepts no request body.

Request

POST

/auth/api/v1/auth/logout

curl -X POST https://your-sphere.example.com/auth/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (204 No Content)

// No response body

POST/auth/api/v1/auth/logout/all

Logout all sessions

Revoke all active tokens and sessions for the authenticated user across all devices. This is useful when a user suspects their account has been compromised or wants to sign out everywhere.

This endpoint requires authentication and accepts no request body.

Request

POST

/auth/api/v1/auth/logout/all

curl -X POST https://your-sphere.example.com/auth/api/v1/auth/logout/all \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (204 No Content)

// No response body

POST/auth/api/v1/auth/switch-context

Switch context

Switch the authenticated user's active tenant or workspace context. This issues a new token set scoped to the specified tenant and/or workspace. The previous tokens remain valid until they expire.

Use this endpoint when a user belongs to multiple tenants or workspaces and needs to switch between them without re-authenticating.

Optional attributes

Name
tenant_id
Type
string
Description
The UUID of the tenant to switch to. The user must be a member of this tenant.
Name
workspace_id
Type
string
Description
The UUID of the workspace to switch to within the current or specified tenant.

Request

POST

/auth/api/v1/auth/switch-context

curl -X POST https://your-sphere.example.com/auth/api/v1/auth/switch-context \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  }'

Response

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "def50200c3b2a1f6e5d4...",
    "token_type": "Bearer",
    "expires_in": 3600
  },
  "meta": {
    "services": {
      "auth": "https://your-sphere.example.com/auth",
      "core": "https://your-sphere.example.com/core",
      "chat": "https://your-sphere.example.com/chat",
      "voip": "https://your-sphere.example.com/voip",
      "drive": "https://your-sphere.example.com/drive",
      "activity": "https://your-sphere.example.com/activity",
      "usermanager": "https://your-sphere.example.com/usermanager",
      "notes": "https://your-sphere.example.com/notes",
      "mail": "https://your-sphere.example.com/mail"
    }
  }
}

GET/auth/api/v1/auth/config

Get auth configuration

Retrieve the public authentication configuration for the Sphere instance. This is a public endpoint that does not require authentication. Use it to discover which MFA methods are available, password policy requirements, and other auth-related settings before rendering login or registration forms.

Request

GET

/auth/api/v1/auth/config

curl https://your-sphere.example.com/auth/api/v1/auth/config

Response

{
  "data": {
    "mfa_methods": ["totp", "otp", "magic_link", "webauthn"],
    "password_policy": {
      "min_length": 8,
      "require_uppercase": true,
      "require_lowercase": true,
      "require_number": true,
      "require_special": false
    },
    "session": {
      "token_lifetime": 3600,
      "refresh_token_lifetime": 604800,
      "max_active_sessions": 10
    },
    "lockout": {
      "max_attempts": 5,
      "lockout_duration": 900
    }
  }
}