Fictura
Overview

Authentication

Four credentials for servers, one for browsers — which key goes in which header, and what each is allowed to do.

CredentialFormatHeaderScope
SDK app keygk_ + 48 hexx-api-keyOne app. Config, event ingestion, errors, traces, request sessions, deploys, surveys, push registration, and the entitlements check.
Links API keyfk_live_…Authorization: BearerThe Links API (/v1/links…). Secret — shown once at creation, stored hashed, revocable.
MCP keyfk_mcp_… (fk_mcpw_… when it can edit)Authorization: Bearer or x-api-keyThe MCP server (/mcp) and nothing else. Reads, plus only the writes it was minted for. Secret — shown once at creation, stored hashed, revocable.
Data API keyfk_data_…Authorization: BearerOnly its scopes: events:read for the Events and Persons APIs and Bulk export, users:delete to delete a person, events:import for historical import, sourcemaps:upload to upload source maps and symbols, releases:write to record deploys. Secret — shown once at creation, stored hashed, revocable.
Dashboard sessionJWTAuthorization: Bearer + x-app-idThe operator endpoints the dashboard itself uses. Not for server integrations.

The SDK app key

From Dashboard → Setup, always retrievable. It identifies your app rather than authenticating a person — treat it as publishable. A missing key answers 401 {"ok": false, "error": "missing x-api-key"}; an unknown one 401 … "unauthorized". The key selects the app: querying an entitlement with app A's key can only ever see app A's users — another app's user id simply answers status: "none".

Minted on Dashboard → Links → API. The plaintext appears exactly once, in the create response; only a hash is stored, so nobody — including Fictura — can read a key back later. Revocation is immediate: a revoked key fails on its next request, no cache window. Each key records last_used_at, so an unused key is visibly unused before you rotate it away.

Data API keys

Minted on Dashboard → Setup → Keys & webhook → Data API keys, where you tick the scopes the key gets. Stored and revoked exactly like a Links key. A key without a scope cannot reach that scope's routes (403 missing_scope); give a warehouse loader events:read and nothing else, and keep users:delete for the service that handles deletion requests. The panel offers every scope except events:import; Historical import says how to mint that one. On a backend that predates scoped keys, the panel is hidden.

MCP keys

Minted on Dashboard → Setup → Coding agents (MCP), and stored and revoked exactly like a Links key. It authenticates the MCP server that AI coding agents read your app through, and nothing else. It reads everything the dashboard shows and writes only what it was minted for: draft paywalls and onboarding flows with Can edit drafts, an AppsFlyer import with Can connect and import data — never anything live. Someone working in Claude, ChatGPT or an editor can sign in with Fictura instead of using a key.

The fk_ surfaces do not overlap, because each accepts only its own kind of key: an MCP key sent to the Links API is rejected, and a Links key sent to /mcp or the Data APIs is too. That separation keeps a key handed to an agent inside what the MCP server allows, since the Links API can create and change links.

cURL
# SDK app key — x-api-key
curl https://api.fictura.co/api/v1/entitlements/8f14e45f \
  -H "x-api-key: gk_..."

# Links API key — Bearer
curl https://api.fictura.co/v1/links \
  -H "Authorization: Bearer fk_live_..."

# Data API key — Bearer
curl https://api.fictura.co/api/v1/events \
  -H "Authorization: Bearer fk_data_..."

# MCP key — Bearer, and both Accept values are required
curl -X POST https://mcp.fictura.co/mcp \
  -H "Authorization: Bearer fk_mcp_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Two base paths, not two versions

/api/v1/… (SDK and app surface) and /v1/… (the public Links API) are separately authenticated surfaces, not versions of each other. There is exactly one API version today. Two SDK routes sit under /v1 but take the SDK app key: /v1/traces and /v1/resolve.

On this page