API keys

An API key is what tells Gyrence which workspace a request belongs to. Every call to /api/v1/* carries a key in the Authorization header, and that key — not the caller's identity — is what we bill, log, and rate-limit against.

Keys are minted in the console, scoped to one workspace, and revocable at any time.

Anatomy of a key

mc_VHJ5dGhpc2lzbm90YXJlYWxrZXk
└┬┘ └─────────────┬─────────────┘
 │                │
 │                └── 32 chars of url-safe random (24 bytes, base64url)
 └─── fixed prefix

Every key starts with mc_ followed by 32 random URL-safe characters. The plaintext is shown exactly once, at the moment of minting. We store only a SHA-256 hash plus the first 8 characters of the random part (the key prefix, e.g. VHJ5dGhp…) so you can identify a key in the console without ever exposing the full value.

If you lose a key, you can't recover it — revoke it and mint a new one.

Sending a key

All endpoints take the key as a bearer token in the Authorization header:

curl https://www.gyrence.com/api/v1/fetch \
  -H "Authorization: Bearer mc_VHJ5dGhpc2lzbm90YXJlYWxrZXk" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }'

A missing, malformed, or revoked key returns 401 unauthorized. The mc_ prefix is required — keys without it are rejected before the hash lookup.

The same key authenticates the MCP endpoint at POST /api/mcp — header-only, never in the URL path. No separate "MCP key" type exists; an HTTP key works over MCP and vice versa.

Minting and revoking

Keys are managed at Console → API keys, scoped to the currently-selected workspace.

• Mint. Give the key a human name (prod-backend, ci-runner, intern-laptop). The plaintext appears in a one-time reveal — copy it before closing the dialog.
• Revoke. Revocation is immediate. Subsequent requests with that key get 401 unauthorized. Revoked keys stay in the list (greyed out) so the historical audit trail in Usage and Activity remains intelligible.

A workspace can hold as many keys as you like; there is no per-key credit cap (all keys on a workspace share the workspace's credit pool).

Rotation

There's no built-in expiry, but rotating periodically is good hygiene — especially after a teammate leaves, a deploy environment is decommissioned, or a key may have been exposed in a log or screenshot.

The zero-downtime rotation pattern:

1. Mint a new key alongside the old one.
2. Roll the new value out to whatever uses the old key (deploy, CI secret update, etc.).
3. Once traffic on the old key drops to zero (check Usage filtered by key prefix), revoke it.

One key per use, not one key per person

Keys identify a caller, not a human. The clean pattern is:

• One key per deployed environment (prod, staging, dev).
• One key per automation (ci, nightly-batch, webhook-handler).
• A short-lived key per developer laptop during local work — revoked when no longer needed.

This makes the Usage page legible (you can see which surface is burning credits), and it limits blast radius when a single key is exposed.

What a key does not grant

• Console access. Signing in is via your account — keys don't authenticate humans into the dashboard.
• Cross-workspace access. A key is bound to exactly one workspace and cannot be promoted, transferred, or scoped to a different one. Mint a new key on the target workspace instead.
• Selective endpoint access. Today, any valid key can call any /api/v1/* endpoint on its workspace. Per-key scopes are on the roadmap, not shipped.

Common patterns

• Per-environment keys with matching workspaces. Pair acme-prod workspace + prod-backend key, acme-staging workspace + staging-backend key. Credits, usage, and blast radius all stay separate.
• Short-lived dev keys. Mint a dev-laptop-<name> key for local exploration; revoke it the same day. Cheaper than building a key-vault around a long-lived shared key.
• One key per integration. If you call Gyrence from three services, give each its own key. When one starts misbehaving, you can revoke without disrupting the others.