Authentication

Authentication and API keys

Understand session tokens, API keys, validation flows, and how credentials behave across the API, CLI, SDKs, and MCP.

Credential types

TSFM.ai supports two main credential shapes: short-lived session tokens for interactive account flows and longer-lived API keys for service-to-service work. Both travel in Bearer format, but they serve different operational needs. New accounts start with 500 free API credits before billing is required for programmatic inference.

Auth reference

Field	Type	Required	Description
Session token	Bearer token	Conditional	Issued by `/api/auth/register` or `/api/auth/login`; best for interactive account flows. Browser-cookie sessions can use the web playground, while programmatic bearer use still consumes free credits or metered billing.
API key	Bearer token	Conditional	Created on `/api/account/keys`; intended for server-to-server inference and automation.
Credential validation	POST /v1/validate	No	Accepts `api_key` or bearer header and returns `{ valid, auth_type, user, key? }`.

Create and rotate

Create credentials in the right place

Most teams should create their user account in the UI, then generate environment-specific API keys from Account → API Keys. Direct registration is useful for local testing or automated demos.

curl -X POST https://api.tsfm.ai/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "founder@company.com",
    "password": "change-me-before-prod",
    "name": "Forecast Team"
  }'

Rotation checklist

Create API keys from `/account/keys` and label them by environment or workload.
Store server-side keys in secret management, not in browser code or checked-in config files.
Validate new keys immediately after creation using `/v1/validate`.
Rotate keys on a schedule and immediately after incident response or team-member offboarding.

Validation

Validate before you debug payloads

If an integration is failing, confirm the credential first. Validation is cheaper than repeatedly invoking inference endpoints and gives you a clear yes/no on whether the presented token or key is usable.

validate.sh

curl -X POST https://api.tsfm.ai/v1/validate \
  -H "Content-Type: application/json" \
  -d '{"api_key":"'$TSFM_API_KEY'"}'

Surface behavior

How credentials behave across integration surfaces

HTTP API

Use `Authorization: Bearer <token-or-key>` for account and inference requests. Programmatic inference consumes free credits first, then metered billing if billing is active.

SDKs

Pass `apiKey` / `api_key` explicitly or rely on `TSFM_API_KEY` for local development and CI.

CLI

Use `--api-key` or environment variables. CLI commands exit non-zero on auth failures, which is ideal for automation.

MCP

Hosted MCP flows use OAuth 2.1 for supported clients. Custom clients should authenticate the MCP transport with a Bearer token such as an OAuth token, API key, or session token; MCP usage follows the same credits and billing rules as the API.