# 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](https://tokst.com/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`:

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

```bash
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

```bash
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

| Token | Duration | Refresh |
|---|---|---|
| JWT Access Token | 1 hour | Auto-refreshed by CLI and MCP server |

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:

| Limit | Value |
|---|---|
| Authentication exchange | 10 requests per minute |
| Usage tracking | 60 requests per minute |
| Embedding generation | 30 requests per minute |
| Upload URL requests | 30 requests per minute |

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:

| Plan | Monthly Operations | Storage |
|---|---|---|
| **Free** | 1,000 | 500 MB |
| **Starter** | 2,000 | 2 GB |
| **Pro** | 10,000 | 10 GB |
| **Team workspace** | 20,000 shared | 20 GB shared |
| **Legacy Max / Team** | Existing entitlement | Existing entitlement |

Check your usage anytime:

```bash
tokst status
tokst status --json    # For programmatic consumption
```

## Revoking vs. Deleting Keys

| Action | Effect |
|---|---|
| **Revoke** | Key is immediately deactivated. Cannot be re-enabled. Existing tokens issued by this key remain valid until expiry. |
| **Delete** | Key is permanently removed. All associated tokens are invalidated immediately. |

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:

```bash
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).