How-to

Authentication

Every 10ex API and the MCP server accept the same two credentials. Pick the one that matches who’s calling.

Bearer JWT

Issued by the user-login flow (POST /api/v1/users/login). Short-lived, scoped to a single user. Best for:

Local development from your own account
The product UI (already wired in)
MCP clients running on a developer’s machine

Send as Authorization: Bearer <jwt>.


curl -X POST https://api.10ex.ai/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@acme.com", "password": "..."}'

Sample response:


{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 3600
}

A 401 Unauthorized means the token is missing, malformed, or expired. Refresh by logging in again.

First-party API key

Long-lived, hashed with argon2 in the database. Format: tnx_<prefix>_<secret>. Best for:

Production integrations
Server-side scripts
MCP clients running in shared infrastructure

Send as Authorization: Bearer tnx_abc12345_<secret>.

Minting

In v1, API keys are minted via the Starlette admin panel. A self-serve UI is tech debt #21. Until that ships, ask an admin to mint a key for you and put rotation on a schedule.

Scopes

v1 keys carry scope ['*'] (all tools). Per-tool scopes (leads:write, campaigns:write, and so on) are tech debt #20. Build your code as if scopes already exist so you can flip them on later without refactoring.

Rotation

Keys can be revoked from the admin panel. Revoked keys reject immediately on the next request. Always rotate on team turnover, and never check keys into git.

Which should I use?

Caller	Pick
Your own laptop hitting the API for testing	JWT
A cron job in production	API key
Claude Desktop or Cursor on your machine	Either, JWT is easier
A shared CI runner	API key

Common questions

What happens if I send both headers? Don’t. We read Authorization once. The first valid bearer wins.

Can I scope an API key to a single workspace? Workspace scoping is implicit. A key minted in workspace A only sees workspace A.

Is there an OAuth flow for third-party apps? Not in v1. If you’re building a public integration, contact us at developers@10ex.ai.

API keys: full minting and rotation guide
Rate limits: per-credential throttling