Manage API keys and service accounts

You will learn how to create and revoke personal API keys in Tixio, connect MCP clients, call the REST API with X-API-Key, and administer workspace service accounts.

Read API keys and programmatic access first if you want the model before the steps. For scope details, read API key scopes.

Create a personal API key

Open your workspace, then go to Settings > API keys.

You can also open API keys from the command palette when you are in a workspace.

On the API keys page:

Choose New key.
Enter a Name that identifies the client (for example Cursor or Claude Desktop).
Choose Create key.
Copy the token from the Save this key now banner and store it somewhere safe.
Choose I have saved it when you are done.

Tixio shows the full tix_… token only once. If you lose it, revoke the key and create a new one, or rotate via the REST API (see below).

The key list shows active keys with prefix, created time, and last-used time. Revoked keys stay visible in a dimmed Revoked section so you can see what used to be active.

Revoke a personal API key

On Settings > API keys, find the key in Active and choose Revoke.

Confirm the dialog. Any client using that token stops working immediately.

You can also revoke every personal key at once when you change your password: open Settings > Account security, enable Revoke all API keys, then update your password.

Rotate a key or set scopes (REST)

The web UI creates personal keys with full permissions. To rotate a key or assign scopes at creation time, use the REST API with your interactive session (JWT bearer token).

Create a scoped personal key:

curl -sS -X POST "https://your-tixio-host/v1/api-keys" \
  -H "Authorization: Bearer $TIXIO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-readonly","scopes":["issues:read","projects:read"]}'

Rotate a personal key (new token, 7-day grace on the old one):

curl -sS -X POST "https://your-tixio-host/v1/api-keys/$KEY_ID/rotate" \
  -H "Authorization: Bearer $TIXIO_JWT"

The rotate response includes the new tix_… secret once. Update your client within the grace window, then retire the old value after seven days.

Pass an optional workspace_id in the JSON body when you want the action recorded in that workspace's audit log.

Connect Cursor

Cursor reads MCP server configuration from ~/.cursor/mcp.json (or a workspace-local equivalent).

For a hosted Tixio instance, use the Streamable HTTP transport and your personal API key:

{
  "mcpServers": {
    "tixio": {
      "url": "https://your-tixio-host/v1/mcp/http",
      "headers": {
        "X-API-Key": "tix_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
      }
    }
  }
}

Replace your-tixio-host with your Tixio API hostname and paste the key you saved from Settings > API keys.

Restart Cursor or reload MCP servers. Tixio tools should appear under the MCP badge in the composer.

Hosted MCP defaults to a lean core tool surface (common issue, project, cycle, search, and comment workflows). To advertise the full non-alias catalog on a self-hosted or stdio MCP process, set TIXIO_MCP_TOOL_TIER=full. Prefer get_issue(issue_id=<key>, workspace_id=...) and update_issue for cycle/epic changes; legacy aliases such as get_issue_by_key are not advertised.

If your key is scoped, ensure it includes the scopes the tools you need require. An empty scope list grants full access for your user.

Connect Claude Desktop

Claude Desktop supports the same remote url + headers shape:

{
  "mcpServers": {
    "tixio": {
      "url": "https://your-tixio-host/v1/mcp/http",
      "headers": {
        "X-API-Key": "tix_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
      }
    }
  }
}

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or the equivalent path on your platform), paste your key, and restart Claude Desktop.

Classic SSE transport is also available at /v1/mcp/sse if your client requires it. Send the same X-API-Key header on every SSE and message request.

Call the REST API with X-API-Key

Send your API key on each request with the X-API-Key header:

curl -sS "https://your-tixio-host/v1/workspaces/$WORKSPACE_ID/projects" \
  -H "X-API-Key: tix_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

When both Authorization: Bearer … and X-API-Key are present, Tixio prefers the API key. This avoids accidental use of a stale browser token in scripts.

Scoped keys receive 403 Forbidden when a route or MCP tool requires a scope they do not have. Unscoped keys behave like your normal permissions (personal) or the service account's project roles.

Key management endpoints (POST /v1/api-keys, rotate, revoke) require an interactive JWT session — you cannot manage keys using another API key.

Administer service accounts

Service accounts are workspace-owned integrations identities. Workspace owners and admins manage them through the REST API under /v1/workspaces/{workspaceId}/service-accounts.

Create a service account

curl -sS -X POST "https://your-tixio-host/v1/workspaces/$WORKSPACE_ID/service-accounts" \
  -H "Authorization: Bearer $TIXIO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"release-bot","description":"Posts release notes to issues"}'

Assign project access

Grant the service account a role on a project:

curl -sS -X PUT \
  "https://your-tixio-host/v1/workspaces/$WORKSPACE_ID/service-accounts/$SA_ID/projects/$PROJECT_ID/role" \
  -H "Authorization: Bearer $TIXIO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"role":"member"}'

Use admin, member, viewer, or guest as the role value. The service account can only touch projects where you assign a role.

Issue a service account key

curl -sS -X POST \
  "https://your-tixio-host/v1/workspaces/$WORKSPACE_ID/service-accounts/$SA_ID/api-keys" \
  -H "Authorization: Bearer $TIXIO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod","scopes":["issues:read","issues:write"]}'

Use the returned tix_… token in X-API-Key the same way as a personal key. Rotate and revoke through the service-account key endpoints; rotation uses the same 7-day grace period.

Disable a service account

When an integration is retired, disable the service account so its keys stop working:

curl -sS -X POST \
  "https://your-tixio-host/v1/workspaces/$WORKSPACE_ID/service-accounts/$SA_ID/disable" \
  -H "Authorization: Bearer $TIXIO_JWT"

Review Settings > Audit log for api_key.* and service-account events when you need an administrative trail.