Authentication and scopes

Overview

Formuley authenticates REST API requests with bearer tokens created from the authenticated developer area.

Manage keys at /developer/api-keys.

Bearer token format

All REST requests use this header:

Authorization: Bearer flmy_live_xxxxxxxxxxxxxxxx

The current API middleware accepts the flmy_live_... key format.

Where keys are managed

Use these authenticated pages:

• /developer for overview and usage status
• /developer/api-keys to create or revoke keys
• /developer/docs for request examples and endpoint reference

Scope model

API keys are scope-based. Current scope families are:

• formulas:read, formulas:write
• ingredients:read, ingredients:write
• batches:read, batches:write
• orders:read
• labels:read, labels:write
• compliance:read
• bulk:read, bulk:write
• exports:read, exports:write
• data:read
• webhooks:read, webhooks:write

Write scope implies read access for the same family, so formulas:write also satisfies formulas:read.

Scopes do not override plan gating. For example, raw data endpoints require Lab or Enterprise, export jobs require Enterprise, and SCIM uses a separate token model entirely.

Key management recommendations

• Create one key per integration instead of sharing a single key across systems.
• Start with the narrowest scope set that works.
• Revoke unused keys rather than keeping dormant credentials active.
• Use the developer logs to troubleshoot failures before widening scopes.

Rate limits

API limits are per day and reset at midnight UTC.

Current defaults in code are:

• Business: 1,000 requests per day
• Lab: 10,000 requests per day
• Enterprise: unlimited

Custom key-level overrides can exist, so the value shown inside /developer is the real operational source of truth for a specific account.

Common failures

• 401 unauthorized means the key is missing or malformed.
• 401 invalid_api_key, revoked_api_key, or expired_api_key means the token is known but unusable.
• 403 feature_not_available means the current plan does not include API access.
• 403 insufficient_scope means the key exists but lacks the required scope.
• 429 rate_limit_exceeded means the account hit its current daily limit.

Expected result

After this page, you should be able to:

• create the right key
• send a valid bearer token
• choose scopes intentionally
• interpret auth and rate-limit errors correctly

Next docs

• API overview
• Webhooks
• Data sync and exports