Authentication

Trinity supports three authentication methods: admin password login, email verification login, and MCP API keys. All authenticated API calls require a Bearer token in the Authorization header.

Concepts

JWT Token -- All authenticated API calls require a Bearer token in the Authorization header. Tokens use HS256 signing, are valid for 7 days, and are invalidated when the backend restarts. Logging out revokes the token immediately (a server-side blacklist holds it until its natural expiry) — an exfiltrated token dies with the session instead of living out its 7 days.
MCP API Key -- Keys prefixed with trinity_mcp_ also work as Bearer tokens. Used for MCP server authentication and agent-to-agent communication.
Agent-Scoped Key -- An MCP API key restricted to a specific agent, used for agent-to-agent calls.

Admin Login

POST

/api/token

Admin login using form-encoded POST (not JSON). Returns a JWT bearer token. The username field accepts admin or the admin's registered email address.

curl -s -X POST http://localhost:8000/api/token \
  -d 'username=admin&password=your-password'

# Response
{"access_token": "eyJ...", "token_type": "bearer"}

Email Login (2-step)

POST

/api/auth/email/request

Step 1: Request a verification code sent to the user's email.

curl -X POST http://localhost:8000/api/auth/email/request \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

POST

/api/auth/email/verify

Step 2: Verify the code and receive a JWT token on success.

curl -X POST http://localhost:8000/api/auth/email/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "code": "123456"}'

# Response
{"access_token": "eyJ...", "token_type": "bearer"}

Using Tokens

Include the token in the Authorization header for all authenticated requests. MCP API keys (trinity_mcp_*) can be used in the same way as JWT tokens.

curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/agents

What a Key Is Not

An MCP key resolves to the user who owns it, carrying that user's role. On a default installation where the admin owns the agents, an agent's injected key would therefore satisfy a plain "admin only" check.

Endpoints whose blast radius is operator-scale therefore require a human caller in addition to an admin role — API keys of any scope are rejected, regardless of the owner's role. This applies to:

Approving an oversized data-retention deletion
Restarting or reinitializing the system agent
Registering, editing, or syncing a skill source
Reading an agent's credential checklist
Reading, verifying, or rotating an agent's own MCP key (these additionally require an interactive browser session)
Binding an agent to a GitHub repository
Writing an agent evaluation
Adding or removing organizational (dept-* / reports-to-*) tags

If you hit a 403 on one of these from an automation, that is the gate working as intended — perform the action from the UI or with a user session.

API Endpoints

Endpoint	Method	Auth	Description
/api/token	POST	None	Admin login (form-encoded)
/api/auth/email/request	POST	None	Request email verification code
/api/auth/email/verify	POST	None	Verify email code, returns token
/api/auth/mode	GET	None	Get auth mode configuration
/api/auth/logout	POST	JWT	Revoke the current token immediately (idempotent; no-op for MCP keys)
/api/auth/validate	GET	JWT	Validate current token (rejects revoked tokens)
/api/users/me	GET	JWT	Get current user info
/api/setup/status	GET	None	First-time setup status
/api/health	GET	None	Health check
/api/mcp/keys	POST	JWT	Create MCP API key
/api/mcp/keys	GET	JWT	List MCP API keys
/api/mcp/keys/{id}	DELETE	JWT	Revoke an MCP API key

MCP API Keys

POST

/api/mcp/keys

Create a new MCP API key. Keys are prefixed with trinity_mcp_ and can be scoped to a specific agent.

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-key", "agent_name": "research-agent"}' \
  http://localhost:8000/api/mcp/keys

# Response
{
  "id": "key_abc123",
  "name": "my-key",
  "key": "trinity_mcp_...",
  "agent_name": "research-agent",
  "created_at": "2026-03-26T12:00:00Z"
}

GET

/api/mcp/keys

List all MCP API keys. Key values are redacted in list responses.

DELETE

/api/mcp/keys/:id

Revoke an MCP API key. The key will immediately stop working for authentication.

MCP API keys management interface showing key creation and listing

MCP API keys management in the Trinity dashboard

Unauthenticated Endpoints

The following endpoints do not require a Bearer token:

/api/auth/mode/api/setup/status/api/token/api/health

Full interactive API docs are available at http://localhost:8000/docs when running locally (Swagger UI). See also the MCP Integration guide for MCP API key usage and agent-to-agent auth.

API Reference Agents API