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.
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.

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

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/validate	GET	JWT	Validate current token
/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