API Keys and Permissions

API keys let external tools — SDKs, MCP servers, scripts, and third-party integrations — authenticate with the Helmdesk API. Each key can be scoped to specific permissions and restricted by IP address.

Creating an API Key

Navigate to your project in the dashboard

Go to Settings > API Keys (or click API Keys in the sidebar)

Click Create API Key

Enter a name that describes what the key is used for (e.g., "Production MCP", "CI Pipeline", "Monitoring Script")

Choose a scope preset or select individual scopes

Optionally enter IP addresses or CIDR ranges to restrict usage

Click Create and copy the key immediately — it will not be shown again

Scope Presets

Helmdesk provides five presets to make key creation fast:

Full access — all scopes enabled. Use for admin integrations.

Read only — tickets:read and articles:read. Use for dashboards and monitoring.

Support agent — tickets:read, tickets:write, articles:read, ai:use. Use for support automation.

Email only — emails:send and emails:manage. Use for transactional email services.

MCP / AI assistant — tickets:read, tickets:write, articles:read, ai:use. Use for Claude Desktop, Cursor, and other AI agents.

Available Scopes

tickets:read — List and view tickets

tickets:write — Create, update, reply to tickets

articles:read — Search and read knowledge base articles

articles:write — Create and edit articles

emails:send — Send transactional emails via templates

emails:manage — Manage email templates and configuration

ai:use — Use AI features (suggest reply, classify, draft)

webhooks:manage — Create and manage webhook endpoints

Backward Compatibility

If a key has no scopes set (empty array), it has full access to all endpoints. This ensures existing keys created before scoped permissions were introduced continue to work without changes.

IP Allowlists

You can restrict an API key so it only works from specific IP addresses. This is useful for production servers with static IPs.

Supported formats:

Single IPv4: 192.168.1.100

Single IPv6: 2001:db8::1

CIDR range: 10.0.0.0/24

If no IPs are configured, the key works from any address.

Editing a Key

You can change a key's name, scopes, and IP allowlist after creation. Go to the API Keys page, click the settings icon on the key, and update the fields. The key value itself cannot be changed or viewed again after creation.

Revoking a Key

To revoke a key, click the revoke button on the API Keys page. Revoked keys immediately stop working. This cannot be undone — create a new key if needed.

Best Practices

Use the narrowest scope possible. A monitoring dashboard only needs tickets:read. Do not grant tickets:write unless the integration needs to modify tickets.

Use separate keys for separate integrations. If your MCP server and your CI pipeline both use the API, create two keys. If one is compromised, you can revoke it without affecting the other.

Add IP allowlists for production keys. If your integration runs on a known server, restrict the key to that IP.

Name keys descriptively. "Production MCP — Claude Desktop" is much more useful than "API Key 3" when you need to rotate or revoke.