An integration authenticates with credentials that carry a role. The role decides which of the 137 API actions it may call, so an integration that only reads invoices should not be able to terminate services.

Create the role first

  1. Open Settings → API and go to the API roles section.
  2. Create a role named for the integration, not for the person — “accounting-export”, not “Sam”.
  3. Grant only the actions that integration calls. Start with none and add as it fails; do not start with everything and trim.
  4. Save.
One role per integration.

A shared role means you cannot revoke one integration without breaking the others, and cannot tell from the log which one misbehaved.

Issue the credentials

  1. In the API credentials section, create a credential.
  2. Associate it with the administrator account it acts as, and with the role you just made.
  3. Give it a description that says which system uses it and who owns that system.
  4. Save. WBAMS shows an identifier and a secret.
  5. Copy the secret now. It is shown once.
Never put the secret in a URL.

Query strings land in server logs, browser history and referrer headers. Send credentials in the request body or headers.

Restrict where it works

Limit the credential to the IP addresses your integration calls from. A credential that works from anywhere works from anywhere it leaks to, and leaked credentials are usually found by scanning, not by targeting.

Test it

  1. Call one harmless read action with the new credentials.
  2. Check the result field in the response, not just the HTTP status — a response with data in it can still be a failure.
  3. Call an action the role does not grant and confirm it is refused. If it succeeds, the role is wider than you think.
  4. Open Settings → API and confirm both calls appear in the log.

Rotating and revoking

  1. Revoke immediately when someone with access leaves, or when a secret may have been exposed.
  2. Rotate by issuing a second credential, moving the integration onto it, then deleting the first — not by deleting first and causing an outage.
  3. Review the list periodically and delete anything whose description you no longer recognize.

One thing that changed in 1.5.0

Action names kept their spelling: getcancelledpackages still works as a deprecated alias for getcanceledpackages. But a returned status that used to read Cancelled now reads Canceled. An integration comparing against the literal string must be updated.