API Keys & Authentication

API keys authenticate CI, servers, and unattended REST or MCP automation. Human CLI and remote MCP setup use browser authorization by default.

Creating API Keys

API keys are created from the TokST Web Dashboard.

1. Log in to the dashboard
2. Navigate to API Keys in the sidebar
3. Click Create Key
4. Give the key a descriptive name (e.g., "Development", "CI Pipeline", "Agent Claude")
5. Copy the key immediately — it is shown only once

Key Format

tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The prefix tk_live_ identifies it as a production key. All keys follow this format regardless of the plan.

Key Storage

When you create a key, TokST stores a SHA-256 hash of it server-side. The raw key is never stored — if you lose it, you must revoke and create a new one.

Locally, the CLI stores credentials in ~/.tokst/config.json:

{
  "apiKey": "tk_live_xxxx",
  "accessToken": "eyJhbGci...",
  "anonKey": "sb_publishable_xxxx",
  "tokenExpiresAt": "2026-07-09T10:57:47.306Z",
  "supabaseUrl": "https://pdjpdivokmcevxdrvtfb.supabase.co",
  "apiKeyId": "c699987e-..."
}

The MCP server reads this same file for authentication.

Authentication Flow

Browser setup for people and local agents

curl -fsSL https://tokst.com/install.sh | bash

The script downloads a checksum-verified standalone TokST CLI, then opens TokST for authorization. It requires only a Unix terminal and curl.

API key login for automation

tokst login --key tk_live_xxxx

What happens:

1. The CLI sends the API key to the TokST API
2. The server verifies the SHA-256 hash against stored keys
3. On success, the server returns a JWT access token (valid for 1 hour)
4. The CLI stores both the API key and the JWT in ~/.tokst/config.json
5. Subsequent API calls use the JWT, which auto-refreshes before expiry

Token Lifecycle

You generally don't need to worry about token expiry — the CLI and MCP server handle refresh automatically.

Rate Limiting

Edge service routes apply rolling per-user limits:

Exceeding these limits returns HTTP 429 (Too Many Requests). Rate limits reset on a rolling 60-second window.

Monthly Quotas

Usage is tracked per user against monthly quotas, which vary by plan. The counter increments atomically, so concurrent agent calls cannot overwrite one another:

Check your usage anytime:

tokst status
tokst status --json    # For programmatic consumption

Revoking vs. Deleting Keys

In the dashboard, use Revoke for immediate permanent deactivation while retaining the audit record. Use Delete to remove the key record.

Usage and Per-Key Audit Logs

Personal quota counters belong to the user. A Team workspace uses its shared subscription counter. API key logs identify which key performed each action. The dashboard shows:

• Total operations this month
• Operations by day (chart)
• Last used timestamp
• Key name and creation date

This separates quota enforcement from per-key audit attribution.

MCP Server Auto-Auth

The MCP server authenticates automatically by reading ~/.tokst/config.json. No environment variables or manual configuration steps are needed — it picks up credentials from the same file that tokst login creates.

To override for a non-interactive process, set the TOKST_API_KEY environment variable:

TOKST_API_KEY=tk_live_xxxx bun x -y @tokst/mcp-server

Security Best Practices

• Use descriptive key names so you can identify their purpose in the dashboard
• Create separate keys for development, production, and each agent/integration
• Rotate keys periodically by creating a new key, updating your integrations, then revoking the old one
• Never commit keys to version control — use environment variables or secret managers
• Check usage regularly via the dashboard to detect unexpected activity
• Revoke compromised keys immediately from the dashboard

Agent Quick Setup

To give an AI agent (Claude Code, Cursor, Codex, ZCode, etc.) access to TokST, share this one link:

https://tokst.com/skill.md

The agent reads the document, installs the CLI, and follows the matching Skill and MCP setup. Place the document in the client Skill directory when that client supports Skills; use the displayed MCP configuration for tool access.

You can also copy a ready-made setup script or SKILL.md directly from the API Keys page in the dashboard (click Copy for Agent on any key).