Authentication and errors

API keys

Create an API key under Settings → API Keys. Send it with every authenticated REST request:

Authorization: Bearer inf_sk_your_key

Keep keys on your server. Do not embed them in browser JavaScript, commit them to a repository or include them in public URLs. Manage API keys.

The CLI can also use a browser-login session token. MCP OAuth uses the same routes with its own scopes and contract behavior; see authoring.

Workspaces and permissions

Select a workspace explicitly. X-Innflow-Workspace: personal restricts resource reads to your personal workspace. Omitting the header uses legacy user-owned resource scope, which can also include organization resources you created. To select an organization you belong to, pass its ID:

X-Innflow-Workspace: organization_id

Use List workspaces to discover IDs and roles. Permission checks are endpoint-specific: workflows use read/write/execute actions; execution reads use executions:read; workspace discovery uses workspaces:read. Organization members with read-only roles cannot mutate or execute workflows. A key does not grant access to another user's resources.

Request and response format

Send Content-Type: application/json with JSON bodies. Most successful responses wrap results in data. List workflows and List executions also return pagination with page, pageSize, totalCount and totalPages. Their default page size is 20 and maximum is 100.

Catalog and log endpoints use data.items with nextPage; field options and payloads use nextCursor. Follow the endpoint-specific format rather than assuming one pagination envelope for every route.

Idempotency and retries

Optional keys have a maximum length of 200 characters. Required authoring keys must contain 1–200 letters, digits, dots, colons, underscores or hyphens. Reusing a key with a different request body returns 409. Replays include X-Idempotent-Replayed: true. Keys are scoped to the authenticated principal, workspace and route.

For ordinary optional-key writes, expired receipts can be replaced after 24 hours. For transactional authoring, an expired receipt returns IDEMPOTENCY_EXPIRED; inspect the workflow before starting another operation.

Optional-key response replay is not an exactly-once guarantee: concurrent first requests or a failure before receipt persistence can repeat work. Serialize retries and inspect ambiguous outcomes.

On a network failure, retry eligible writes with the same key and the exact same body. Use backoff for reads and honor Retry-After on rate limits. Inspect resource state before repeating a write without idempotency support.

Errors

Application handler errors generally include:

{
  "error": "Workflow not found",
  "code": "NOT_FOUND",
  "requestId": "request_identifier"
}

Some errors include details. Handler responses include X-Request-Id; retain it when asking support about a request. Proxy failures can have a different envelope.

Rate limits

The application proxy currently applies 60 requests per minute per client IP and route pathname to /api/v1. This is a process-local guard, not a guaranteed account-wide quota. Additional credential or infrastructure limits may apply.

Proxy responses expose X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix milliseconds). A proxy 429 also includes Retry-After in seconds. Build clients around response headers rather than a fixed request rate.