REST API: Authentication

API key and JWT authentication for the Trix REST API.

Updated Oct 6, 2026

Overview

All API requests require authentication. Trix supports two authentication methods: API keys for server-to-server communication and JWT tokens for user-based access.

API Key Authentication

API keys are the recommended authentication method for backend services and scripts. Include your API key in the Authorization header using the Bearer scheme:

Authorization Header

Authorization: Bearer gdb_xxxxxxxxxxxxxxxxxxxxxxxx

Creating API Keys

Create API keys in the dashboard or via the API:

create-key.sh

curl -X POST "https://api.trixdb.com/v1/accounts/api-keys" \
  -H "Authorization: Bearer YOUR_EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "description": "Key for production backend service",
    "expires_at": "2027-12-31T23:59:59Z",
    "is_account_admin": false
  }'

Fields accepted by POST /v1/accounts/api-keys:

name (required) — human-readable label
description (optional)
expires_at (optional, ISO 8601 datetime, nullable) — key deactivates after this timestamp
is_account_admin (optional, boolean, default false) — grants full account admin privileges

API Key Prefixes

Prefix	Type	Description
`gdb_`	Standard	General purpose API key

Keep your API keys secure. Never expose gdb_ keys in client-side code or public repositories.

JWT Authentication

For user-facing applications, use JWT tokens obtained after login:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Login Flow

jwt-flow.sh

# 1. Login to get token
curl -X POST "https://api.trixdb.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your_password"}'

# Response
{
  "message": "Login successful",
  "user": {...},
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

# 2. Use token for requests
curl -X GET "https://api.trixdb.com/v1/memories" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Today every key has a single permission dimension: is_account_admin (boolean). Admin keys can create/delete spaces, manage other keys, configure webhooks, and access billing. Non-admin keys can read, write, and delete memories within the account.

Planned. A full scope system (memories:read/write/delete, sessions:manage, etc.) and per-key IP allowlists are designed in ADR-142. Until it ships, treat non-admin keys as read/write/delete across the whole account.

Space Scoping

Limit an API key to specific spaces for multi-tenant applications. Scoping happens in two calls: create the key, then attach it to each allowed space.

scoped-key.sh

# 1. Create the key (non-admin)
curl -X POST "https://api.trixdb.com/v1/accounts/api-keys" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tenant A Backend",
    "description": "API key for Tenant A",
    "is_account_admin": false
  }'

# 2. Attach the key to a space — repeat per space
curl -X POST "https://api.trixdb.com/v1/accounts/api-keys/KEY_ID/spaces/SPACE_ID" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

# Revoke access to a specific space later:
curl -X DELETE "https://api.trixdb.com/v1/accounts/api-keys/KEY_ID/spaces/SPACE_ID" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

Scoped keys can only access memories within their attached spaces, providing isolation for multi-tenant architectures.

Code Examples

const response = await fetch('https://api.trixdb.com/v1/memories', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer gdb_your_api_key',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Security Best Practices

Rotate keys regularly - Create new keys and revoke old ones periodically
Use minimal permissions - Grant only the permissions each key needs
Scope to spaces - Limit keys to specific spaces when possible
Set expiration dates - Use expires_at for temporary access
Monitor usage - Check API key usage in the dashboard
Use IP allowlists — Planned (ADR-142); account-level geo policy works today

If you believe an API key has been compromised, revoke it immediately in the dashboard or via DELETE /accounts/api-keys/:id.

Auth Endpoints Reference

Method	Endpoint	Description
`POST`	`/auth/register`	Create new user account
`POST`	`/auth/login`	Login and get tokens
`GET`	`/auth/me`	Get current user info
`POST`	`/auth/change-password`	Change password
`POST`	`/auth/forgot-password`	Request password reset
`POST`	`/auth/reset-password`	Reset password with token
`POST`	`/auth/verify-email`	Verify email with token
`PATCH`	`/auth/profile`	Update user profile
`POST`	`/accounts/api-keys`	Create API key
`GET`	`/accounts/api-keys`	List API keys
`DELETE`	`/accounts/api-keys/:id`	Revoke API key