Public API and AI assistants (MCP)
This page is for the developers who connect your organization's own tools to the workspace. On the Enterprise plan, an owner creates API keys on the Enterprise page. A key lets a program read your organization's workspace in two ways: through a REST API, for your own tools and data warehouse, and through an MCP server (Model Context Protocol), which connects AI assistants. A key can only read: nothing reachable with a key can change anything.
API keys
Enterprise → API keys → Create the key: name it, pick its scopes, and optionally an expiry. The key (ak_…) is shown once: store it in your secret manager. Only a hash is kept.
A key acts as the member who created it, narrowed to its scopes. It sees exactly what that member can see: other organizations never, restricted projects only if the creator is on them, and nothing an information barrier hides from the creator. If the creator loses their role or leaves, the key stops working. Revoke stops it at once.
| Scope | Reads |
|---|---|
organization:read |
The organization's name and plan, and the key's own scopes |
projects:read |
Projects |
issues:read |
Issues |
initiatives:read |
Initiatives (restricted ones only for their owner and team) |
events:read |
The event feed webhooks deliver |
audit:read |
The audit log (the creator must be, and stay, an owner) |
mcp:read |
Connecting an assistant to the MCP server (its tools need scopes too) |
Requests on each key lists its calls for the last 90 days: when, which route or MCP tool, the answer and how long it took.
REST API
Send the key as a bearer token:
curl -H "Authorization: Bearer ak_…" https://<api host>/v1/api/projects
Routes: /v1/api/organization, /v1/api/projects, /v1/api/projects/{id}, /v1/api/issues, /v1/api/issues/{id}, /v1/api/initiatives, /v1/api/events (paged with after) and /v1/api/audit-events (paged with before). The OpenAPI document is at /v1/api/openapi.json, needs no key, and names each route's scope in x-api-scope.
A route outside a key's scopes answers 403. Each key has a per-minute limit (600 by default; the deployment may set another); over it the API answers 429 with Retry-After.
MCP server
Point an MCP client at https://<api host>/v1/mcp (streamable HTTP), with the header Authorization: Bearer ak_… and a key holding mcp:read. Its tools are read-only: get_organization, list_projects, get_project, list_issues, get_issue, list_initiatives, list_events and list_audit_events. A tool whose scope the key lacks answers with an error the assistant can read, naming the scope.