Authentication

API keys for machines, JWTs for humans

Tanso has two authentication surfaces, matching its two APIs.

Client API - API keys

Everything under /api/v1/client/** (and the MCP server at /mcp) authenticates with a long-lived API key. Keys are prefixed sk_test_ or sk_live_, and both header forms work:

# Either of these
-H "X-API-Key: sk_test_..."
-H "Authorization: Bearer sk_test_..."

Requests without a valid key get 401. Every call is scoped to the key’s account, so there is no cross-account access.

Managing API keys

API key management requires an Admin API JWT. Retrieval returns only a masked value:

curl http://localhost:8080/api/v1/account/api-key \
  -H "Authorization: Bearer $TOKEN"

Rotate the key when you need a new secret:

curl -X POST http://localhost:8080/api/v1/account/api-key \
  -H "Authorization: Bearer $TOKEN"

Rotation invalidates all previous account keys atomically. The response to the POST contains the new key in full exactly once; later GET responses are masked. Store the rotated key in your secret manager before leaving the response.

Admin API - JWT

All /api/v1/** routes outside the Client API require a session token from login. This JWT-protected surface includes:

• /api/v1/monetization/** for the catalog, rules, subscriptions, credits, and billing.
• /api/v1/account/** for account details.
• /api/v1/tanso/** for events, imports, settings, and model pricing.
• /api/v1/data/** for Stripe data and imports.
• /api/v1/analytics/** for analytics and insights.

Log in to obtain a token:

curl -X POST http://localhost:8080/public/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"password"}'

The response contains a JWT; pass it as Authorization: Bearer <token>. Tokens are signed with your JWT_SECRET and expire after 2 hours.

Which API do I use?

You are…	Use
Your product’s backend checking entitlements, reporting usage	Client API, API key
Defining plans, features, pricing rules	Admin API, JWT
An AI agent operating the platform	MCP, API key

The split exists so the credentials you embed in your application can never alter your catalog or pricing.