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

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 revoke or rotate a project key at any time from the same page. A rotated-out key stays valid for 24 hours, so you can roll a new key into your deployed services without downtime. See Security for the full authentication model.

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 from your account settings. 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. 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

Personal API keys

Creating and managing personal keys

Best practices

​Key types at a glance

​Project API keys

​Creating and managing project keys

​Personal API keys

​Creating and managing personal keys

​Best practices

Key types at a glance

Project API keys

Creating and managing project keys

Personal API keys

Creating and managing personal keys

Best practices