API Keys

Every call to the runtime REST API (/api/v1/runtime/*) and the MCP endpoint (POST /mcp) authenticates with a Bearer API key. This page covers the full lifecycle: creation, scopes, use, rotation, revocation, and operational hygiene.

Keys are always workspace-scoped. They inherit their workspace's subscription tier for rate limiting and quotas, and they carry an explicit set of scopes that gate what they can call.

Creating a key

Keys are created from Agent Setup in the Triggo web app at /agent-setup. Open the API Keys panel, click Create, give the key a human-readable name (use one per integration — claude-desktop, ci-pipeline, zapier-bridge, etc.), select the scopes it needs, and optionally set an expiry date.

Keys have the format trg_<24 random bytes, base64url>. The trg_ prefix plus the first four characters of the random part make up the 8-character public prefix that is stored in clear and shown in the UI for later identification (for example trg_AbCd****).

The plaintext key is shown exactly once — at creation time. Triggo does not store it. The server keeps only a salted SHA-256 hash (sha256(salt + rawKey), with a unique 16-byte random salt per key) and the 8-character prefix. Lose the plaintext and you must rotate — there is no recovery path. Copy the key into your secret store immediately.

The number of active keys per workspace is capped by tier: free plans get 1, starter 3, pro 10, and business unlimited. Revoked keys do not count against the quota.

Scopes

Every API key carries an explicit list of scopes. The server enforces them on both runtime REST endpoints and MCP tools — a tool or endpoint that needs actions:run will reject a key that only has actions:read with HTTP 403.

The canonical scope set is:

If you omit the scopes field when creating a key, it defaults to actions:read, actions:run, runs:read, connectors:read, workflows:read, workflows:write — enough for a typical agent to discover and run published actions, poll results, and manage workflows. Follow least-privilege: don't add approvals:decide, connectors:write, or workflows:run unless the integration really needs them.

All nine scopes above are canonical and mintable on API keys today — there is no longer a gap between the MCP tools' declared scope requirements and what Bearer API keys can request.

Using a key

Send the raw key in an Authorization: Bearer … header on every runtime request. No cookies, no X-API-Key, no query parameters.

curl -sS https://api.triggo.ai/api/v1/runtime/actions \
  -H "Authorization: Bearer trg_YOUR_API_KEY" \
  -H "Accept: application/json"

On success you get the action list plus rate-limit headers (x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset). On failure you get a structured error body and, if rate-limited, a retry-after header in seconds. The MCP endpoint (POST /mcp) uses the same Bearer header — see the MCP quickstart for transport details.

Rotation

Rotate keys on a schedule (quarterly is a reasonable default) and whenever an integration changes hands, a laptop is lost, or a secret-store policy demands it. The pattern is zero-downtime:

1. Create a new key with the same scopes as the old one.
2. Deploy the new key to every caller and verify requests succeed against it (inspect logs, check the key's lastUsedAt).
3. Revoke the old key.

Both keys are active during the overlap window, so no request ever sees a gap. Triggo exposes a one-click rotation in the UI as well: it atomically creates a replacement key with the same name, scopes, and expiry, then revokes the original. If your deploy is not atomic, prefer the manual three-step flow so you control the overlap.

Revoking

Revoke a key from the Agent Setup panel. Revocation flips isActive = false and stamps revokedAt; the next validateKey() call from any caller fails with 401 Unauthorized and "API key revoked". There is no undo — create a fresh key if you need to restore access.

In-flight runs are not cancelled. A run started under a now-revoked key continues to completion in the executor — the key only gates inbound HTTP/MCP calls, not background execution. What stops working immediately is further polling, approvals, and replays via that key. Use a different, live key to read the run's final status, or watch it in the web UI.

A revoked key frees a slot against the per-tier quota, so you can replace a leaked key even on the free plan's single-key allotment.

Security notes

• Never commit keys to source control. Read them from environment variables or a secret manager: TRIGGO_API_KEY=trg_…. Add trg_ to any secret scanner's allow-list patterns.
• One key per integration. If Claude Desktop, your CI pipeline, and a Zapier bridge all share a key, you cannot revoke one without breaking the others. Separate keys also give you per-integration lastUsedAt signal.
• Revoke immediately on suspected leak. Rotate downstream, then investigate — don't wait.
• Prefer tight scopes. A key for a read-only dashboard needs actions:read + runs:read and nothing else. A key that only runs one published action needs actions:run + runs:read.
• Set expiry dates for temporary integrations (demos, short-lived contractors). Expired keys fail auth automatically without needing a manual revoke.
• Treat the plaintext like a password. The server redacts keys in logs (showing only the 8-character prefix), but anywhere else in your stack — CI logs, error reporters, screenshots — it's your responsibility.

Related

• Agent integration overview — when to use REST vs MCP.
• MCP quickstart — wiring an MCP-native client.
• Rate limits — per-tier limits, sliding window, and 429 handling.