Authentication

Fictix exposes a Console-first access model. Use the narrowest layer that supports your workflow, and obtain customer-facing credentials from the Fictix frontend—not from browser source code or a shared admin secret.

Choose a runtime key

Both use X-API-Key. Organization keys are currently available in staging; see One key for multiple companies for company selection, scope settings, and complete examples.

Project runtime API key

For a company you created or selected in the Console, open Company settings and create a project-scoped key under Company API keys. This is the normal key for connecting your server to generated company data and native-shaped routes.

X-API-Key: <project_api_key>

The project's Connect to your builder panel supplies the exact base URL, slug, environment variable names, and first request. Project administrators can rotate or revoke keys in the Console. The full key is only displayed when it is created or rotated.

Use project keys only under the generated company runtime:

GET /api/v1/orgs/{slug}/info
GET /api/v1/orgs/{slug}/data/{entity}
GET /api/v1/orgs/{slug}/export/{entity}
GET /api/v1/orgs/{slug}/native/{service}/{object_type}
POST /api/v1/orgs/{slug}/native/{service}/{object_type}

Do not send a project key to /api/v1/demo-jobs control-plane routes.

For provider calls, native reads need read, and native writes need write. Some native reads use POST with JSON, GraphQL, XML, or form bodies. Execute reads need both read and execute; execute writes need write and execute. FCI uses the execute transport. The staging company's API page provides provider-specific first requests and indicates the required access. See Connect your software for full examples.

Console bearer session

The signed-in Fictix Console uses a WorkOS-backed bearer session for its own management flows, including creating or controlling companies through /api/v1/demo-jobs. The Console manages this session in the app; it is not a customer integration credential, has no customer environment variable, and must never be copied from browser tools or forwarded to another service.

Approved external management credential

External server-to-server callers using management creation and lifecycle routes under /api/v1/demo-jobs must use the Fictix-supplied admin key: FICTIX_ADMIN_API_KEY as X-Admin-Key.

Admin-key example:

X-Admin-Key: $FICTIX_ADMIN_API_KEY

This credential is not a self-service customer credential. Do not use an email/password login, copy a bearer token from browser developer tools, or put the admin key in frontend code. Normal Console customers should create or select a company in the Console, which manages its own WorkOS bearer session, and use the project X-API-Key for subsequent runtime access instead.

Idempotency

POST /api/v1/demo-jobs requires an idempotency key when you have approved control-plane access:

Idempotency-Key: <stable-client-generated-key>

Rules:

• Use a unique key for each new company creation.
• Reuse the same key only when retrying the same request body.
• If the same key is reused with a different body, Fictix returns 409.
• Treat 409 as a client bug or stale retry state.

Good keys:

customer-demo-acme-2026-07-02
load-test-run-7dbe3a8c
crm-import-smoke-20260702T120000Z

Bad keys:

demo
test
retry

Tenant scope

Approved management integrations are scoped by the Fictix account and tenant permissions attached to their server-side credential. Project runtime keys are scoped to one generated company. For customer-facing products, keep each customer/environment in the appropriate organization and rotate a project key instead of sharing it between unrelated integrations.

An organization runtime key spans all companies currently owned by its organization and can list them through GET /api/v1/organizations/{org_id}/companies. It does not grant management authority. Use a separate key per integration so each can be revoked independently.

Browser safety

Never expose:

• X-Admin-Key
• raw company or organization runtime API keys
• Stripe/WorkOS/server secrets

If browser code needs to initiate a customer action, keep the credentialed operation in the Fictix Console or proxy it through your backend. A safe flow looks like:

Browser -> Fictix Console UI or your backend -> Fictix management API

not:

Browser -> Fictix with project or admin key in JavaScript

Common auth failures

Missing management credentials

Symptom:

{
  "detail": "Not authenticated"
}

Fix:

• for an external integration, verify it is approved and send X-Admin-Key: $FICTIX_ADMIN_API_KEY
• in the Console, stay signed in so the Console can manage its bearer session
• verify the environment points to the intended Fictix host

Wrong auth layer

Symptom:

{
  "detail": "Project API key is not valid for this route"
}

Fix:

• for an external integration, use the Fictix-supplied X-Admin-Key: $FICTIX_ADMIN_API_KEY for /demo-jobs; the Console uses its managed WorkOS bearer session
• use company runtime keys under /orgs/{slug}; staging organization keys also access their own /organizations/{org_id}/companies directory

Expired bearer token

Symptom:

{
  "detail": "Token expired"
}

Fix:

• rotate or renew the approved admin key through Fictix, or sign in again to refresh the Console session
• retry once with the renewed credential
• never copy a bearer token from browser developer tools or a Console session