Authentication

Xentree supports two authentication methods for protected endpoints:

Bearer token for user-session requests

X-API-Key for server-to-server integration requests

Supported auth flow

Access token

Use the access token in the Authorization header:

API key

Use API key in the X-API-Key header:

API keys are scope-based. Recommended scopes:

conversations:read, conversations:write

rag:read, rag:write

quiz:read, quiz:write

live:read, live:write

organizations:read, organizations:write

integrations:read, integrations:write

xel:read, xel:write

api:read, api:write, api:admin

Grant only the scopes needed by your integration. For read-only integrations, use only :read scopes.

Refresh token

Xentree also supports session refresh via the refresh endpoint.

Main endpoints

Register

Create a new user account.

POST /api/auth/register

Exchange username and password for an access token.

POST /api/auth/token

Content type: application/x-www-form-urlencoded

Refresh session

Issue a fresh access token.

POST /api/auth/refresh

Logout

Invalidate the current session.

POST /api/auth/logout

Current user

Return the authenticated user profile.

GET /api/auth/me

This endpoint is bearer-only.

Update current user profile

Patch profile-level attributes for the current user.

PATCH /api/auth/me

This endpoint is bearer-only.

Integration token hardening (RS256, tenant-scoped)

Integration grants are tenant-isolated and signed with tenant key pairs.

Issue grant

POST /api/integration/grant

Auth: Bearer or X-API-Key (with integrations:write)

Representative request:

{
  "mode": "api",
  "origin": "https://partner.example.com",
  "scopes": ["profile:read", "quota:read"],
  "ttlSeconds": 120
}

Verify grant token

POST /api/integration/verify

Auth: Bearer or X-API-Key (with integrations:read)

Representative request:

{
  "token": "<integration-jwt>",
  "tenantId": "<tenant-id>"
}

Revoke grant token immediately (JTI revoke list)

POST /api/integration/revoke

Auth: Bearer or X-API-Key (with integrations:write)

Representative request:

{
  "integrationToken": "<integration-jwt>",
  "reason": "security-incident"
}

Alternative request using JTI:

{
  "tenantId": "<tenant-id>",
  "jti": "<token-jti>",
  "reason": "manual-revoke"
}

Rotate grant and optionally revoke old token

POST /api/integration/rotate

Auth: Bearer or X-API-Key (with integrations:write)

Representative request:

{
  "mode": "api",
  "origin": "https://partner.example.com",
  "scopes": ["profile:read"],
  "ttlSeconds": 120,
  "revokeIntegrationToken": "<old-integration-jwt>"
}

Public verification metadata

GET /api/integration/jwks

GET /api/integration/fingerprint

Query params: tenantId

Admin observability (revocation registry)

GET /api/admin/integration-token-revocations

Common query filters: tenant_id, jti, include_expired, limit

Rate limit response headers

Integration endpoints emit rate-limit headers on token issuance/verification paths (grant, verify, and rotate):

X-RateLimit-Limit

X-RateLimit-Remaining

X-RateLimit-Reset

Retry-After (present on HTTP 429)

Representative 429 response detail:

{
  "detail": "Rate limit exceeded for grant. Try again in <seconds> seconds."
}

Common authentication errors

401 Unauthorized

Returned when the bearer token or API key is missing, expired, malformed, or invalid.

403 Forbidden

Returned when a valid principal lacks permission for the requested resource.

For API keys, this can indicate insufficient key scope.

Representative insufficient scope response:

{
  "detail": {
    "error": "INSUFFICIENT_API_KEY_SCOPE",
    "message": "API key lacks required scope for this endpoint",
    "required_scope": "conversations:write",
    "granted_scopes": ["conversations:read"]
  }
}

Best practices

store tokens securely

store API keys securely and rotate them periodically

always send requests over HTTPS

refresh access tokens before long-running sessions expire

revoke sessions on logout or device disconnect

Supported auth flow#

Access token#

API key#

Refresh token#

Main endpoints#

Register#

Login#

Refresh session#

Logout#

Current user#

Update current user profile#

Integration token hardening (RS256, tenant-scoped)#

Issue grant#

Verify grant token#

Revoke grant token immediately (JTI revoke list)#

Rotate grant and optionally revoke old token#

Public verification metadata#

Admin observability (revocation registry)#

Rate limit response headers#

Example login request#

Common authentication errors#

401 Unauthorized#

403 Forbidden#

Best practices#

Supported auth flow

Access token

API key

Refresh token

Main endpoints

Register

Login

Refresh session

Logout

Current user

Update current user profile

Integration token hardening (RS256, tenant-scoped)

Issue grant

Verify grant token

Revoke grant token immediately (JTI revoke list)

Rotate grant and optionally revoke old token

Public verification metadata

Admin observability (revocation registry)

Rate limit response headers

Example login request

Common authentication errors

401 Unauthorized

403 Forbidden

Best practices