API Keys

API keys provide server-to-server access to the Xentree API without requiring user session tokens.

Each key is scoped to an organization, carries a set of permission scopes, and can be optionally restricted to specific IP addresses or CIDR ranges.

Core capabilities

create scoped API keys tied to an organization

list keys visible to the current user

revoke a key immediately by deleting it

restrict keys to specific IPs or CIDR ranges

set optional expiry dates per key

Key format

All Xentree API keys use the prefix xntr- followed by 86 URL-safe base64 characters, totalling 91 characters.

xntr-<86 characters>

The full key value is returned only once at creation time and is never stored in plaintext. Copy it immediately and store it securely.

Authentication

API Key endpoints are bearer-only. Use your user session token to manage keys.

Available scopes

Grant only the scopes your integration needs. Current available scopes:

Scope	Description
`conversations:read`	Read conversation history
`conversations:write`	Send messages and manage conversations
`rag:read`	Search the knowledge base
`rag:write`	Upload and index documents
`quiz:read`	Read quiz content and quiz results
`quiz:write`	Submit quiz answers and manage quiz attempts
`live:read`	Read quota and transcripts
`live:write`	Manage live sessions and nicknames
`organizations:read`	Read organization and member data
`organizations:write`	Manage organizations and members
`integrations:read`	Read integrations and verify tokens
`integrations:write`	Manage integrations and issue grants
`xel:read`	Read English learning modules and scores
`xel:write`	Submit evaluations and track progress
`api:read`	Read generic API metadata and read-level admin API actions
`api:write`	Execute write-level admin API actions
`api:admin`	Full API administration scope

REST endpoints

List API keys

Return all API keys visible to the current user. Non-admins only see keys they created.

GET /api/admin/api-keys

Create an API key

Issue a new scoped API key tied to one of your organizations.

POST /api/admin/api-keys

Representative request:

{
  "name": "Production LMS Integration",
  "organization_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "permissions": ["conversations:read", "conversations:write"],
  "rate_limit_per_minute": 60,
  "expires_at": null,
  "allowed_ips": ["203.0.113.42", "10.0.0.0/8"]
}

Delete an API key

Permanently revoke a key. Any integration using it will fail immediately.

DELETE /api/admin/api-keys/{key_id}

IP allowlist

Set allowed_ips to a list of IPv4/IPv6 addresses or CIDR ranges to restrict where the key can be used. If null or empty, the key is usable from any IP.

Using an API key

Pass the key in the X-API-Key header for all requests:

Core capabilities#

Key format#

Authentication#

Available scopes#

REST endpoints#

List API keys#

Create an API key#

Delete an API key#

IP allowlist#

Using an API key#