API keys and programmatic access

You will learn how Tixio API keys let you connect MCP clients, scripts, and integrations without sharing your password or interactive session.

This page explains the concepts. For step-by-step setup, use Manage API keys and service accounts. For the scope catalog, read API key scopes.

Why API keys exist

API keys are long-lived credentials for programmatic access. Use them when a tool needs to call Tixio on your behalf outside the web app — for example Cursor, Claude Desktop, a CI job, or a webhook manager.

API keys are separate from your sign-in session. Revoking a key stops that client without signing you out everywhere else.

Personal keys vs service accounts

Tixio supports two kinds of API credentials:

Kind	Owned by	Permissions	Typical use
Personal API key	Your user account	Inherits your workspace and project access	MCP clients, personal scripts, local automation
Service account key	The workspace	Project roles you assign to the service account	Shared integrations, CI, bots that should not depend on one person

Personal keys act as you. If you can read or edit an issue in the UI, a personal key with full permissions can do the same through the API or MCP.

Service accounts are workspace-owned identities with no human login. A workspace owner or admin creates the service account, assigns a project role (Admin, Member, Viewer, or Guest) on each project it should touch, and issues keys for that account. Disabling the service account stops all of its keys.

Choose a personal key when only you need access. Choose a service account when the integration should outlive any one teammate or run with narrower project access.

Token format

New keys use the tix_ prefix:

tix_<prefix>_<secret>

Tixio shows the full token exactly once when you create or rotate a key. After that, you only see the prefix and masked secret (for example tix_ab12cd34_••••••••••••••••••••••••••••••••••).

Store the token in a password manager or secret store. There is no way to recover the secret later — create a new key or rotate instead.

Scopes

Each key can carry an optional scope list that limits what it may do. Scopes are an allowlist, not a grant of extra power.

Empty scopes mean full permissions for that key's identity (personal user access or the service account's project roles).
Non-empty scopes restrict the key to the listed capabilities, such as issues:read or webhooks:manage.

Scoped keys still respect normal workspace and project membership. A scoped key cannot bypass access you would not have in the UI.

For the full list, read API key scopes.

Rotation and grace period

Rotating a key generates a new token with the same name and scopes. The previous token enters a 7-day grace period during which both old and new tokens work. After grace expires, the old token stops working automatically.

Use rotation when you want to roll credentials without a hard cutover — for example updating a CI secret while the old value still works briefly.

Revoking a key stops it immediately. Revocation does not use a grace period.

Audit visibility

Workspace owners and admins can review API key lifecycle events in Settings > Audit log:

api_key.created — a personal or service-account key was issued.
api_key.rotated — a key was rotated; the event includes the grace expiry.
api_key.revoked — a key was revoked.

Service account administration (create, update, disable) is also recorded in the audit log.

Use the audit log when you need to trace who issued credentials or when an integration last changed keys.

Security practices

Treat API keys like passwords:

Issue one key per client or integration so you can revoke narrowly.
Prefer scoped keys when the client only needs read access or webhook management.
Rotate keys on a schedule or after someone with access leaves the team.
Revoke keys you no longer use.
When you change your account password, consider selecting Revoke all API keys on the Account security page if you suspect exposure.

Personal keys inherit your access — protect them accordingly. Service account keys inherit only the project roles you assign; keep those roles as small as the integration allows.

Remote MCP transports authenticate every request with X-API-Key. Revoking a key blocks new requests immediately. A local MCP process that started with an environment variable keeps using the old key until you restart it.