API keys

Zespan uses two distinct kinds of API keys, scoped differently and used for different things. Project API keys authenticate the SDK when it sends trace data to Zespan. Personal API keys authenticate you when an AI assistant connects to Zespan’s hosted MCP server. This page covers how each is scoped, where to manage it, and how to keep it safe.

Key types at a glance

	Project API key	Personal API key
Prefix	`zsp_`	`lqtp_`
Scope	One project — can only write trace data to the project it was created for	The user who created it — inherits that user’s role and permissions
Used for	SDK tracing/ingest (`zespan.init(...)`), direct API requests via the `x-api-key` header	Connecting an AI assistant (Claude Desktop, Cursor, etc.) to Zespan’s MCP server as a Bearer token
Managed from	The project’s Settings → API Keys page	Your account settings

A third kind, the write-only change key (zsc_), reports changes from CI and is managed on the same page.

Project API keys

A project API key is what the Zespan SDK uses to send trace events for a single project. It starts with zsp_ followed by 64 hex characters, and it is scoped to exactly one project — it can only write trace data to the project it was created for, and it cannot read or write anything in any other project. Use it when initializing the SDK:

zespan.init({
  apiKey: "zsp_your_key_here",
  environment: "production",
});

zespan.init(
    api_key="zsp_your_key_here",
    environment="production",
)

The SDK sends this key as an x-api-key header on requests to the ingest API. If you’re calling Zespan’s API directly rather than through the SDK, set the same header yourself.

Creating and managing project keys

Project API keys are created and managed from that project’s Settings → API Keys page. The key is shown in full only once, at creation — copy it somewhere safe immediately, since Zespan cannot show it to you again. You can rotate a project key at any time from the same page. Rotating asks you to confirm, shows the new key once, and keeps the previous key valid for 24 hours so you can roll the new one into your deployed services without downtime. The page shows “Previous key still valid until …” while that window is open; after it, anything still using the old key is rejected.

Rotating again while a previous key is still in its 24 hours ends that older key immediately. Only the key you replaced most recently gets the grace period, so finish rolling out a new key before you rotate a second time.

Members who aren’t an owner or admin can open the page, but rotating is turned off for them. See Security for the full authentication model.

Change keys

A change key (zsc_ followed by 48 hex characters) is for a CI pipeline that reports deploys and config changes to the change timeline. It is write-only: it can call POST /v1/changes and POST /v1/projects/{id}/changes and nothing else, so every other route answers 403 with change_key_scope. A leaked pipeline secret therefore cannot read your data or run anything that costs money. Create and revoke change keys under Settings → API keys → Change keys (owner or admin). The key is shown once. The list shows each key’s first 12 characters, when it was created and when it was last used. A revoked key stops working on its next request. See Report changes from your CI.

Personal API keys

A personal API key authenticates you — not a project — and is used specifically to connect an AI assistant to Zespan’s hosted MCP server. It starts with lqtp_ and is sent as a Bearer token:

{
  "mcpServers": {
    "zespan": {
      "url": "https://api.zespan.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer lqtp_YOUR_PERSONAL_API_KEY"
      }
    }
  }
}

Unlike a project key, a personal key isn’t scoped to a single project — it inherits whatever role and permissions the user who created it has across the organization. That means what the MCP tools can see and do (for example, whether they’re allowed to promote a prompt to production) depends on your role, exactly as it would if you performed the same action from the dashboard.

Creating and managing personal keys

Generate and revoke personal API keys under Settings → MCP keys. Give each one a descriptive name so you can tell them apart later, and treat it with the same care as a password — anyone with your personal key can act as you through any tool that supports MCP.

Keys expire after 90 days by default. Because a personal key acts as you in every organization, the Expires menu starts at 90 days. Choose 30 days, 180 days, 1 year, or No expiry, which keeps the key working until you revoke it. The API accepts any expiresInDays from 1 to 365.
The key is shown once. Copy it before you close the box; leaving without copying it means generating a new one.
You can have up to 10 keys. The page shows how many you use, when each was created, when it last connected, and flags keys that have expired or expire soon.
Revoking is immediate. Any assistant using the key loses access right away.

If an organization you belong to requires two-factor authentication and you aren’t an owner, you need a verified authenticator app before you can create a personal API key. Without one, MCP requests to that organization’s projects are refused — including with keys you created before the requirement was turned on.

See Zespan MCP server for the full client setup for Claude Desktop, Cursor, and other MCP clients.

Best practices

Never commit keys to source control. Load them from environment variables (ZESPAN_API_KEY, or similar) instead of hardcoding them in your codebase.
Use a distinct project key per environment. Separate keys for development, staging, and production mean you can revoke or rotate one without affecting the others.
Rotate keys periodically, and immediately if you suspect a key has leaked.
Scope access deliberately. Only generate a personal API key for MCP if you actually need an AI assistant querying your data, and revoke it when you no longer need it.

For the full security model — encryption, tenant isolation, and how keys are stored — see Security.

AI Providers (BYOK)

Deployment

Security & Compliance

Account

Key types at a glance

Project API keys

Creating and managing project keys

Change keys

Personal API keys

Creating and managing personal keys

Best practices

​Key types at a glance

​Project API keys

​Creating and managing project keys

​Change keys

​Personal API keys

​Creating and managing personal keys

​Best practices

Key types at a glance

Project API keys

Creating and managing project keys

Change keys

Personal API keys

Creating and managing personal keys

Best practices