One key for multiple companies

An organization API key lets your server access every current and future company in one Fictix organization. The same key can access 100 companies; each request selects one company by its runtime slug.

Organization keys are available in staging. Use https://api-staging.fictix.ai for the examples on this page. Production continues to support company keys until this feature reaches production. Account limits still apply to company creation and usage.

Create the key

Sign in to the staging Console and open the organization that owns your companies.
Open its Settings, then Organization API keys. You must be an organization admin or owner.
Choose a name, access level, and expiry, then select Create organization key.
Copy the full key while it is displayed and save it in your server's secret store.

The full secret is displayed only when a key is created or rotated. Key lists show a masked prefix, status, scopes, usage, and expiry.

Access setting	Scopes	Use
Read only	`read`	Read company data and list companies
Read and modify	`read`, `write`	Read and modify supported runtime records
Full runtime	`read`, `write`, `execute`	Also call the execute transport

Runtime operations retain their existing scope requirements. An organization key does not grant company creation, membership, billing, key-management, or other actions that require a signed-in Console session. Ground-truth access requires the separate, explicit ground_truth scope; Full runtime does not include it.

List available companies

Keep these values on your server:

export FICTIX_API_ORIGIN="https://api-staging.fictix.ai"
export FICTIX_ORGANIZATION_ID="replace_with_organization_id"
export FICTIX_ORGANIZATION_API_KEY="replace_with_organization_key"

curl --fail-with-body -sS \
  "$FICTIX_API_ORIGIN/api/v1/organizations/$FICTIX_ORGANIZATION_ID/companies?limit=100&offset=0" \
  -H "X-API-Key: $FICTIX_ORGANIZATION_API_KEY"

The organization ID appears in the directory request shown below the key controls. A response has this shape; the identifiers below are fictional:

{
  "organization_id": "example_org",
  "companies": [
    {"id": "company_a", "name": "Fictional Estate Software", "slug": "estate-software-demo", "status": "ready", "org_id": "example_org"},
    {"id": "company_b", "name": "Fictional Advisory Services", "slug": "advisory-services-demo", "status": "ready", "org_id": "example_org"}
  ],
  "count": 2,
  "total": 2,
  "limit": 100,
  "offset": 0
}

For this directory, count is the number returned on the current page and total is the number in the organization. Continue while offset + count < total. The maximum limit is 1,000.

Select a company on each request

Change the slug and keep the same key:

curl --fail-with-body -sS \
  "$FICTIX_API_ORIGIN/api/v1/orgs/estate-software-demo/data/customers?limit=10" \
  -H "X-API-Key: $FICTIX_ORGANIZATION_API_KEY"

curl --fail-with-body -sS \
  "$FICTIX_API_ORIGIN/api/v1/orgs/advisory-services-demo/data/customers?limit=10" \
  -H "X-API-Key: $FICTIX_ORGANIZATION_API_KEY"

/organizations/{org_id} identifies your Fictix organization. The older /orgs/{slug} runtime path identifies a generated company. For execute request bodies, the legacy org_id field is the selected company's id; it is not the organization ID from the directory URL.

Company keys continue to work for their own company. An organization key cannot access a company owned by another organization. Moving a company out removes that organization's key access; moving one in allows its new organization's keys to access it.

Rotate and revoke

Rotate creates a replacement and immediately revokes the previous key, while preserving its scopes and expiry. Save the replacement and update your server. If you need an overlap during rollout, create a second key, update your integrations, and then revoke the first key.

Revoke stops that key across all companies in the organization. Expired and revoked keys return 401. A valid key selecting a company outside its organization returns 404 (Project not found). If you receive 404, check the company slug and the organization that owns it.

Keep the key out of frontend JavaScript, public environment variables, and source control. The Company API reference documents runtime requests; routes requiring Console bearer authentication remain separate.

Authentication

Demo jobs