API keys

We authenticate the public API with API keys. One key lets you call search, enrichment, MCP V2/Core, and the SDKs — same org, same credits, same chargeInfo. MCP V3 signs you in with OAuth instead. Create live keys in the dashboard; pass them in the request (or a header); revoke them when a script or teammate no longer needs access.

What it does

1. Mint a live key at fiber.ai/app/api (name it, copy the secret, store it as FIBER_API_KEY).
2. Send that key on every call — body/query apiKey, or x-api-key / Authorization: Bearer.
3. Keep a sandbox key for local and CI work so tests do not draw down credits.
4. List, limit, expire, or revoke keys from the dashboard or the API-key operations below (use a live key for those).

Chargeable product calls still consume credits on live keys. Key management itself is free. See Billing & credits.

Create and store a key

Sign in, open fiber.ai/app/api, and create a key. Give it a name you will recognize later (prod-enrichment, local-dev). The full secret appears once. After that the dashboard shows the prefix, created date, and a revoke action.

export FIBER_API_KEY=sk_live_...

Put the export in your shell profile or a secrets manager. Never commit the value. For MCP server configs, prefer "x-api-key": "${env:FIBER_API_KEY}" over pasting the secret into chat — see MCP for AI agents.

The first live key has to come from the dashboard (or sign-up). After you have one, you can mint additional sandbox keys from the API.

Passing the key

Include the key in one of these ways. If both body/query and a header are set, body/query wins.

SDK calls take apiKey on the request object, not a constructor-level Bearer token. Request schemas live on @fiberai/sdk/zod — parse before you call:

import { getOrgCredits } from "@fiberai/sdk";
import type { GetOrgCreditsData } from "@fiberai/sdk";
import { zGetOrgCreditsData } from "@fiberai/sdk/zod";

const creditsRequest: GetOrgCreditsData = zGetOrgCreditsData.parse({
  query: { apiKey: process.env.FIBER_API_KEY! },
});
const credits: Awaited<ReturnType<typeof getOrgCredits>> =
  await getOrgCredits(creditsRequest);
const available: number | undefined = credits.data?.output[0]?.available;

Prefer a header over putting the secret in the URL:

curl -H "x-api-key: $FIBER_API_KEY" https://api.fiber.ai/v1/get-org-credits

Live vs sandbox

Sandbox keys still have to be registered keys for your org — a random sk_test_ string will not authenticate. Successful sandbox responses set the x-fiber-sandbox: true header and return chargeInfo.method: "free".

Not every public operation is sandboxed yet. Those return 501 with "Sandbox mode is not yet available for this endpoint." Use a live key for list / limit / expire / reset / revoke — those management calls are not sandboxed. createSandboxApiKey itself is.

Managing keys from the API

The API key tag is the spec. Each operation also has agent markdown at /ai-docs/<operationId>.md. All of these are free. Call them with a live key.

List and get return name, prefix, expiration, and usage — never the secret. Revoke is permanent; mint a replacement before you kill a key that is still in use. Targeting OTHER plus targetApiKey acts on a different key in the same org; the default is the key you authenticated with.

You cannot create a live sk_live_ key through the API. That stays on the dashboard.

Using it effectively

• One key per environment or workload. Revoking staging then does not take down production.
• Export FIBER_API_KEY. MCP, the plugin, and OpenFiber all read that name.
• Cap a key with updateApiKeyLimit when a contractor or a cron job should not be able to spend the whole org balance. Hitting that ceiling returns 403, not 402.
• 401 means no key was sent (header and body/query were both empty). 403 means the key is invalid, expired, revoked, or over its per-key ceiling. 402 means the org is out of credits or the billing period expired — billing. A key-management POST with a malformed body (including a missing apiKey field on the JSON) can be 400.
• 429 is our rate limit. Back off and retry.

Use cases

Ship a Node or Python job. Create a live key, put it in the environment, call @fiberai/sdk / fiberai, and trust chargeInfo on the response. Start from SDKs.

Wire Claude, Cursor, or Codex. Same key, as an x-api-key header on MCP V2 or Core. Chat UIs that only offer OAuth should use MCP V3 instead — no key. Walkthrough: MCP.

Keep CI off the credit balance. Authenticate with a live key, mint a sandbox key via createSandboxApiKey, then call operations that support sandbox. If an operation is not sandboxed yet, you get 501 — switch that call to a live key or skip it in CI.

Credits

Creating, listing, updating, and revoking keys is free. Calls you make with a live key bill like any other operation — chargeInfo is authoritative. Billing & credits.

Related: Build with Fiber · SDKs · MCP · Developing with AI agents