API keys, webhooks and installs

Create an API key

POST/v1/api-keys

Creates an API key with scopes and a mode, and returns the key once.

The response contains the full key in key. It is shown only once: we store only a hash. Send it as Authorization: Bearer <key>. A key is bound to this account.

scopes are permission keys, and a key can never hold a scope you do not have yourself. At call time the key is limited further to your current permissions: if your role loses a key or you leave the account, the API key loses it on its next request.

mode decides whether the key can send. With draft_only (default), sends need "confirm": true. With auto_send, the key may send documents to clients without confirmation; creating an auto_send key needs a fresh sign-in. Keys are made in Settings > API keys. See Authentication and Drafts and confirmations.

Creating an auto_send key needs a fresh sign-in: a web session that is not fresh gets 401 fresh_signin_required. API keys cannot perform fresh-sign-in actions.
Send an Idempotency-Key header so a retried request never creates two keys.

Permission: integrations.manage
Type: Write. Creates or changes data and writes an audit entry.
Auth: API key, MCP token or signed-in session
Capability: create_api_key
CLI: freeinvoiceautomation key create
Available: At launch, 1 January 2027

create_api_key

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/api-keys \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Accounting export script",
  "scopes": [
    "documents.view",
    "clients.view",
    "payments.view",
    "reports.view"
  ],
  "mode": "draft_only",
  "business_ids": [
    "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f"
  ]
}'

{
  "data": {
    "id": "0193f350-5a6b-7c7d-8e9f-0a1b2c3d4e5f",
    "name": "Accounting export script",
    "prefix": "fia_live_7Hq2",
    "scopes": [
      "documents.view",
      "clients.view",
      "payments.view",
      "reports.view"
    ],
    "mode": "draft_only",
    "business_ids": [
      "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f"
    ],
    "rate_limit_per_minute": null,
    "source": "user",
    "last_used_at": null,
    "expires_at": null,
    "revoked_at": null,
    "created_by": "0193f29d-2c3d-7e4f-9a0b-1c2d3e4f5a6b",
    "created_at": "2027-01-05T12:00:00Z",
    "key": "fia_live_7Hq2kR9vXw3mN8pL5tY1cB6dF0gJ4sZ"
  }
}

Authorizations

Authorizationstringrequired

Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.

Headers

Idempotency-Keystring

Any unique string up to 255 characters. Required for API-key and MCP calls that create something; optional otherwise. See Idempotency.

Body

application/json

namestringrequired

Your name for the key (1 to 100 characters).

scopesstring[]required

Permission keys the key may use, e.g. documents.view. Each must be one you hold.

modeenum<string>default:draft_only

auto_send lets the key send without confirmation and needs a fresh sign-in.

Available options: draft_only, auto_send

business_idsstring<uuid>[]

Limit the key to these businesses. Leave out for every business you can reach.

rate_limit_per_minuteinteger

A lower request limit per minute for this key than the default.

expires_atstring<date-time>

When the key stops working. Leave out for no expiry.

Response

201 - application/json

idstring<uuid>

Id of the key.

namestring

Your name for the key, e.g. Accounting export script.

prefixstring

The first characters of the key, for recognising it. The full key is shown only once, when created.

scopesstring[]

Permission keys the key may use. At call time the key can do only what both its scopes and its creator's current permissions allow.

modeenum<string>

draft_only (default): sends need "confirm": true. auto_send: the key may send documents without confirmation.

Available options: draft_only, auto_send

business_idsstring<uuid>[] | null

Businesses the key is limited to, or null for every business its creator can reach.

rate_limit_per_minuteinteger | null

This key's own request limit per minute, or null for the default.

sourceenum<string>

user for keys you created; connector_install for keys issued to a Shopify or WordPress install.

Available options: user, connector_install

last_used_atstring<date-time> | null

When the key last made a request.

expires_atstring<date-time> | null

When the key stops working, or null for no expiry.

revoked_atstring<date-time> | null

When the key was revoked.

created_bystring<uuid>

The member who created the key. The key never has more permissions than this member has now.

created_atstring<date-time>

When the key was created.

keystring

The full API key. Returned only in this response; store it safely.

Errors

fresh_signin_required

validation_failed

business_out_of_scope

idempotency_key_reused

Plus the common errors every call can return. See Errors.

Suggest edits Raise issue

List API keysPrevious Revoke an API keyNext

curl --request POST \ --url https://api.freeinvoiceautomation.com/v1/api-keys \ --header 'Authorization: Bearer <api-key>' \ --header 'Idempotency-Key: <unique-key>' \ --header 'Content-Type: application/json' \ --data '{ "name": "Accounting export script", "scopes": [ "documents.view", "clients.view", "payments.view", "reports.view" ], "mode": "draft_only", "business_ids": [ "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f" ] }'

{ "data": { "id": "0193f350-5a6b-7c7d-8e9f-0a1b2c3d4e5f", "name": "Accounting export script", "prefix": "fia_live_7Hq2", "scopes": [ "documents.view", "clients.view", "payments.view", "reports.view" ], "mode": "draft_only", "business_ids": [ "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f" ], "rate_limit_per_minute": null, "source": "user", "last_used_at": null, "expires_at": null, "revoked_at": null, "created_by": "0193f29d-2c3d-7e4f-9a0b-1c2d3e4f5a6b", "created_at": "2027-01-05T12:00:00Z", "key": "fia_live_7Hq2kR9vXw3mN8pL5tY1cB6dF0gJ4sZ" } }