API authentication and permissions
Integrations call the admin role with a staff account’s API key. The key does what that staff
account may do, so give each integration its own staff account with only the permissions it needs.
Sign requests with an API key
Section titled “Sign requests with an API key”- Create a staff account for the integration (System → Settings → Staff), in a group with the permissions it needs.
- Sign in as that account, open your staff profile and select API. Copy the API Key. See Connect integrations to the admin API for where it is and how to replace it.
- Send it with HTTP Basic authentication: the user name is
adminand the password is the key.
curl --silent --user "admin:$CLIENTFENCE_API_KEY" \ --header 'Content-Type: application/json' --data '{}' \ https://billing.example.com/api/admin/profile/getUse HTTPS only. A request with a wrong or old key gets Authentication Failed (HTTP 401). The key of a
deactivated staff account stops working.
Staff permissions
Section titled “Staff permissions”Each admin call checks two things, set on the staff group’s Permissions tab:
- Access to the module: without it every call of the module answers
You do not have access to the <module> module(code 725). - The call’s own permission, such as Manage invoices: without it the call answers
You need the "invoice.manage_invoices" permission to perform this action(code 403).
The API reference names both for every call. Super Administrators have every permission; avoid using one for an integration.
Limit the addresses keys work from
Section titled “Limit the addresses keys work from”On Security → Settings → Access lists, API keys from these addresses only takes addresses or
ranges. A request signed with an API key from any other address gets Unauthorized IP (HTTP 401). The
admin and client pages keep working from anywhere. See Proxies, access lists and sessions.
Log API requests
Section titled “Log API requests”Security → Settings → API log records each request signed with a staff API key (and other sources you choose): who, the call, the address, the status and the time, with secrets hidden. The list is in Activity → System Activity → API log.
Client and guest calls
Section titled “Client and guest calls”- Client calls run as the signed-in client in the browser. There are no client API keys. A custom
theme calling them sends the session cookie and the CSRF token, as the
X-CSRF-TOKENheader or aCSRFTokenparameter; a missing or wrong token getsCSRF token invalid(code 403). - Guest calls need no sign-in. The calls that sign in, sign up or change the cart also need the
browser session’s CSRF token, a
POSTand a request from your billing site’s own address.
A client who is an authorized user of another account can make only the calls its permissions allow.
After an update
Section titled “After an update”Until a ClientFence update is finalized (System → Update ClientFence), admin calls answer
ClientFence update finalization is pending (HTTP 503). Retry after the update is finished.

