Authentication
Send the store's API key in X-Auth-Token on every API v3 request.
Last updated
Every API v3 request needs the store’s API key. The key belongs to one store, and everything you do with it is scoped to that store.
Get the key
Section titled “Get the key”- In the Invoice Falcon app, open Settings, then the Integrations tab.
- In the API access section, click Generate API key.
- Click Copy next to the API key field.
The key starts with if_api_key_. It’s the same key API v1 uses. A store has one key at a time.
Send the key
Section titled “Send the key”Send it in the X-Auth-Token header:
curl -s https://app.invoicefalcon.com/api/v3/external/account/plan \ -H "X-Auth-Token: if_api_key_..."Authorization: Bearer if_api_key_... is accepted too, for clients that can only set a bearer token.
Rotate the key
Section titled “Rotate the key”Click Reset next to the API key field in the app, or call the API:
# 1. Without confirm: nothing changes, the 409 says what would happen.curl -s -X POST https://app.invoicefalcon.com/api/v3/external/account/integrations/api_key/rotate \ -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
# 2. With confirm: the old key stops working at once, and the new key is in this response only.curl -s -X POST https://app.invoicefalcon.com/api/v3/external/account/integrations/api_key/rotate \ -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"confirm": true}'Update every integration with the new key straight away.
Authentication errors
Section titled “Authentication errors”| Status | code |
Cause |
|---|---|---|
401 |
unauthorized |
No key sent (API key is required), the key is wrong or was rotated (Invalid API key), or the store uninstalled the app. |
403 |
v3_required |
The store still uses the previous Invoice Falcon dashboard. Use API v1 for now. |
403 |
paid_plan_required |
The store’s plan doesn’t include API access. |
Moving the store to the Free plan deletes the key. After the store upgrades again, generate a new one.
Public documents
Section titled “Public documents”These public documents answer without authentication, so a developer or an agent can read them before a store has a plan:
/api/v3/openapi.jsonand/api/v3/mcp.json/api/v3/external/skill.md, a guide written for AI agents/api/v3/external/help, the action manifest/llms.txt
Security
Section titled “Security”- Keep the key on your server. Never put it in a storefront, a browser app or a public repository.
- Don’t paste it into an AI chat. To connect an AI app, use the MCP server: it refuses the API key on purpose and uses its own sign-in.
Thanks for letting us know.
Still stuck? Ask Quinn or chat with support