API

  Table of Contents

• API Keys
  • API Keys and Service Accounts
• Bulk Endpoints
• API Reference

Factorial's API supports deterministic integrations and data changes outside the user interface. It provides nearly all functionality available through the Factorial application. See Integrations for guidance on combining the API with Factorial's pollable event stream.

API Keys

Factorial authenticates API requests with API keys. Create a key from the Keys page, copy it when it is displayed, and send it in the HTTP Authorization header:

Authorization: Bearer <api-key>

Factorial displays the secret only when the key is created and stores a hash rather than the original value. Keys expire after three months and may be revoked from the Keys page. Use the key's description to identify its purpose, owner, and environment.

Treat an API key like a password. Store it in a secrets manager, exclude it from source control and logs, and rotate it before expiration. Revoke and replace it immediately if it may have been exposed.

API Keys and Service Accounts

For an integration, automation, or AI agent, create a dedicated service-account user. Do not use an employee's account for a long-lived integration. Use a separate service account for each independent workload and assign only the roles it needs.

API key permissions are a snapshot

When an API key is created, Factorial copies the creating user's effective permissions into the key. The key continues to use that copied permission set. Later changes to the user's roles or to the permissions within those roles do not update an existing key.

Changing the service account's roles is therefore not enough to change an existing key. Set the intended roles, create a replacement key, update the integration, and revoke the old key.

Bulk Endpoints

Nearly all of Factorial API endpoints are bulk-friendly. For example, the API does not provide an endpoint that creates one procedure. It provides endpoints that create, update, or delete multiple procedures in one request.

API Reference

The complete API reference is available from the API Docs section of the Factorial documentation center.