Authentication

Every Gyrence API call is authenticated with a workspace API key sent as a bearer token. There is no OAuth, no session cookie, no signed-request scheme — one header, one secret, one workspace.

Authorization: Bearer mc_VHJ5dGhpc2lzbm90YXJlYWxrZXk

The key tells Gyrence which workspace the call belongs to, which credit pool to draw from, and which Usage and Activity logs to write. The caller's human identity is not part of the request.

The header

All endpoints under /api/v1/* expect the same header:

Authorization: Bearer <api-key>

• The scheme is Bearer (case-sensitive in spirit, case-insensitive in practice).
• The key must start with mc_. Anything else is rejected before hash lookup.
• The header is the only place credentials are read. Query-string keys, request-body keys, and basic auth are not supported.

A missing header, malformed key, or revoked key returns:

{ "ok": false, "error": "invalid api key", "code": "unauthorized" }

with HTTP 401. Failed auth is never billed — the request is rejected before any primitive runs.

Getting a key

Keys are minted in the console at API keys, scoped to the currently-selected workspace.

1. Pick the workspace from the switcher in the top-right of the console.
2. Open API keys → New key.
3. Give it a human name (prod-backend, ci-runner, dev-laptop-alice).
4. Copy the plaintext value from the one-time reveal — Gyrence stores only a SHA-256 hash, so the full value can never be recovered.

See Concepts → API keys for the full lifecycle (rotation, revocation, prefixes).

Always call www.gyrence.com

The canonical host is www.gyrence.com. The apex (gyrence.com) issues a 307 redirect to www, and most HTTP clients (curl, fetch, the majority of SDKs) drop the Authorization header on cross-host redirects — so calls to the apex will surface as 401 unauthorized. Always hard-code https://www.gyrence.com in your client, SDK config, and webhook destinations.

A canonical request

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

const res = await fetch("https://www.gyrence.com/api/v1/fetch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GYRENCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});
 
const json = await res.json();
if (!json.ok) throw new Error(`${json.code}: ${json.error}`);

The same key authenticates the MCP endpoint at POST https://www.gyrence.com/api/mcp — header-only, never in the URL path.

Verifying a key without spending credits

GET /api/v1/health is authenticated, costs 0 credits, and never returns 402. Use it as a liveness probe and as a cheap way to confirm a key is valid before promoting it to production.

curl https://www.gyrence.com/api/v1/health \
  -H "Authorization: Bearer $GYRENCE_API_KEY"

{ "ok": true, "data": { "status": "ok" } }

Handling secrets

Keys grant full API access to a workspace and draw down its credit balance — treat them like a database password.

• Server-side only. Never ship a key to a browser, mobile app, or any client your users control.
• Environment variables or a secret manager. Not source code, not config files committed to git.
• One key per deployed surface. Separate keys for prod, staging, CI, and each developer's laptop make revocation surgical.
• Rotate after exposure. A key in a log, screenshot, or shared terminal is compromised. Mint a new one, roll it out, revoke the old one.

What auth does not do

• Endpoint scoping. Any valid key can call any /api/v1/* endpoint on its workspace today. Per-key scopes are on the roadmap.
• Cross-workspace access. A key is bound to exactly one workspace and cannot be promoted, transferred, or pooled. Mint a new key on the target workspace instead.
• Console sign-in. Keys don't authenticate humans into the dashboard — that's a separate account-level login.