API keys

This page lets you create an API key, understand what it authenticates, and revoke it when you are done.

An API key is a per-user bearer credential (spc_k1_…) that authenticates requests to the Spectrace MCP server (MCP is the Model Context Protocol, which AI coding agents use to call tools) — the hosted endpoint at https://spectrace.io/api/mcp and any stdio or self-hosted spectrace-mcp process. It is not accepted by any other endpoint; see What a key authenticates.

Prerequisites

• A Spectrace account that belongs to at least one organization. A key is bound to one of your organization memberships, chosen by the server (the first org_members row it finds); you do not choose the organization when creating it. If you belong to more than one organization, call spectrace_whoami after connecting to see which one the key resolved to.

Create a key

1. Open Settings → Developers

   In the app sidebar choose Settings, then the Developers tab. The deep link is /settings?tab=developers.

2. Click New Key

   In the API Keys section click New Key. The Create New API Key form asks for:

   • Name (required) — a label such as MCP Server or CI/CD Pipeline.
   • Expires — 30 days, 90 days (default), 180 days, 1 year, or Never.

   Click Create Key.

3. Copy the key

   A banner reads API key created! and tells you to copy it now because it cannot be shown again. The key is masked to its first 12 characters; click the eye icon (tooltip Show key) to reveal it and Copy to copy it. Once you click Dismiss, the full key is gone from the UI for good.

You are done when the key appears under Active Keys with its name, its 12-character prefix, its creation date and, if set, its expiry. Create Key stays disabled until you enter a name; if the server rejects the request (for example, your account has no organization membership), the error text appears above the list and no key is created.

Key format and storage

• Format: spc_k1_ followed by 64 hexadecimal characters (32 random bytes), 71 characters in total.
• Display prefix: the first 12 characters (spc_k1_ plus 5 hex characters) are stored and shown in the key list. Nothing else about the key is shown after creation.
• Storage: Spectrace stores a SHA-256 hash of the full key, never the key itself. A lost key cannot be recovered — revoke it and create a new one.
• Legacy prefix: keys issued before the rebrand start with rip_k1_ and keep working. Validation is a hash lookup, so the prefix is display-only.
• Last used: the key list shows "Last used" once the MCP server has accepted the key. Only the MCP server updates this timestamp.

Use a key

Send the key as a Bearer token in the Authorization header:

Authorization: Bearer spc_k1_…

The MCP server parses the scheme case-insensitively and trims surrounding whitespace. For client configuration snippets (Claude Code, Claude Desktop, Cursor) and the stdio SPECTRACE_API_KEY environment variable, see Connect an agent.

On every request to the hosted or self-hosted HTTP endpoint (and once at start-up for a stdio process) the server:

1. Hashes the presented key and looks it up. No row → INVALID_API_KEY.
2. Rejects a revoked key with INVALID_API_KEY and an expired key with API_KEY_EXPIRED.
3. Re-reads your organization role from the membership table. If you have left the organization, the key is rejected with INVALID_API_KEY even though the key row still exists.
4. Derives your permissions from that role (owner, admin, or member; the organization roles Spectrace has). A tool you are not permitted to call returns INSUFFICIENT_PERMISSIONS. See Roles and permissions.

Keys have no scope picker: every key created in the UI carries the full permissions of your organization role, no more and no less. Free-plan organizations can call only spectrace_whoami and spectrace_capabilities.

What a key authenticates

Today an API key authenticates exactly one thing: the MCP server, over the hosted endpoint or a stdio/self-hosted process.

There is no public REST API that accepts an API key. The routes under /api/v1/* are the VS Code extension's backend; they authenticate a Supabase session token issued by the extension's sign-in flow, and a spc_k1_ key sent to them fails with HTTP 401 Invalid or expired token. To integrate programmatically, connect an MCP client — see Connect an agent.

Authentication errors

The hosted endpoint answers an authentication failure with HTTP 401 and a JSON-RPC error envelope:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Unauthorized",
    "data": { "reason": "INVALID_API_KEY" }
  }
}

A browser GET on https://spectrace.io/api/mcp with no header returns an HTML explainer page (also 401) rather than the JSON envelope.

Rate limits

• HTTP layer (hosted endpoint): 300 requests per minute per Bearer token. Exceeding it returns HTTP 429 with Retry-After: 60 and a JSON-RPC error whose data.reason is RATE_LIMIT_EXCEEDED. Successful responses carry X-RateLimit-Limit and X-RateLimit-Remaining.
• MCP tool calls: 100 per minute per user by default, enforced inside the server. Exceeding it returns a tool error Rate limit exceeded. Try again in N seconds.
• Plan allowance: paid plans include a monthly agent-call allowance per organization; spectrace_whoami and spectrace_capabilities are exempt.

Revoke or delete a key

• Revoke: in Active Keys, click the revoke icon (tooltip Revoke key) on the row. Revocation is immediate — the next MCP request with that key fails with INVALID_API_KEY. The key moves to Revoked / Expired.
• Delete: in Revoked / Expired, click the trash icon (tooltip Delete permanently) to remove the row. Expired keys appear in the same list and can be deleted the same way.
• Keys are listed, revoked and deleted per user. An organization admin cannot see or revoke another member's keys from the UI. Deleting your account removes your keys.

There is no key rotation or regenerate action: create a new key, update your clients, then revoke the old one.

Related

• Connect an agent — where the key goes for each MCP client.
• Roles and permissions — how your organization role becomes tool permissions.
• Security — how Spectrace handles credentials and data.