Skip to content

API keys

An API key lets your backend work with one shop. Create it in the dashboard, save it on your server and send it as a bearer token.

In the shop, create a key with read and write permissions. The ivk_ token is shown once; save it immediately. A shop can have up to 10 keys that are not revoked; see Limits.

An agent can create the same key using its login session:

Terminal window
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/keys' \
-H 'Authorization: Bearer <session-token>' \
-H 'Idempotency-Key: <saved-unique-key>' \
-H 'Content-Type: application/json' \
-d '{"name":"backend","scopes":["read","write"]}'

Use a session to create or change keys. An API key cannot create another key. If the account has MFA, key management may require a fresh second factor.

Terminal window
curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/payments?limit=50' \
-H 'Authorization: Bearer ivk_...'
Scope Purpose
read allows reading invoices and deposits, and the merchant’s fees and enabled networks.
write allows everything in the shop: creating, cancelling and switching off invoices and deposits, webhooks, the shop name and branding.

Request both permissions for a backend that creates payments and checks them. Do not assume write automatically includes read.

The key works with its own shop only, and for the whole shop. Only where the shop pays (recipient, delegate, payout target), archiving and the sandbox reset need a login session. With read it also reads its merchant’s fees and enabled networks (GET /api/v1/merchants/{merchant_id}/tariffs and /networks). Everything else about the account and the merchant — sign-in, profile, team, other shops, the merchant overview, API keys, the wallet and the card — needs a login session; a key gets 403 api_key_not_allowed or 401. Never put it in browser code, a payment URL or a shared chat.

Archiving the shop disables all of its keys.

GET /api/v1/me with the key returns the key and what it belongs to:

{"user_id":"…","onboarding_required":false,"mfa_required":false,"key_id":"…","key_name":"backend","scopes":["read","write"],"shop_id":"…","shop_name":"Main shop","sandbox":false,"merchant_id":"…","merchant_name":"Acme"}

Use shop_id in the shop paths; there is no need to list merchants.

Optionally provide allowed_ips when creating or editing a key:

{"allowed_ips":["203.0.113.10","2001:db8::/32"]}

These are example addresses. Replace them with your backend’s actual egress addresses. Up to 10 IPs or CIDR ranges are allowed per key; more returns 400 too_many_allowed_ips. An empty list removes the restriction.

Create a replacement key, update your backend, then revoke the old key with DELETE /api/v1/shops/{shop_id}/keys/{key_id}.

PATCH on the same path can change name, enabled, scopes or allowed_ips. Omitted fields stay unchanged. Editing does not reveal or rotate the token.

Keys work until disabled or revoked, subject to account and shop access. They are not a promise of permanent access. See the API reference for request details.