Skip to content

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.

  1. Create a staff account for the integration (System → Settings → Staff), in a group with the permissions it needs.
  2. 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.
  3. Send it with HTTP Basic authentication: the user name is admin and the password is the key.
Terminal window
curl --silent --user "admin:$CLIENTFENCE_API_KEY" \
--header 'Content-Type: application/json' --data '{}' \
https://billing.example.com/api/admin/profile/get

Use HTTPS only. A request with a wrong or old key gets Authentication Failed (HTTP 401). The key of a deactivated staff account stops working.

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.

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.

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 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-TOKEN header or a CSRFToken parameter; a missing or wrong token gets CSRF 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 POST and 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.

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.