Connect other programs — API tokens and webhooks

What it is for

Two ways connect BrowserDesk with other programs:

• API token: a program — your PSA, a script, a monitoring tool — signs in to the console API with it and reads or changes devices, tickets and sessions as far as the chosen role allows.
• Webhook: BrowserDesk reports events to an address of your system on its own — new tickets, status changes, notes, start and end of sessions, alerts. Alternatively your system fetches them.

For ServiceNow, Jira Service Management and Autotask there are ready-made integrations (G16).

What you need

• API token: your own relay and an account as system administrator of the relay. In the Cloud only the operator creates tokens.
• Webhook: the ticket system in the access (Cloud: booked, own relay: in the licence; never Free) — G14 — and an address the relay can reach.

How to do it

Create an API token (own relay)

1. In the console, bottom left: Users → page Users & roles → API tokens ….
2. Enter a Name (e.g. "HaloPSA"), choose the Role (Read only, Technician, Supervisor or SCIM provisioning), choose Valid (30 days to 1 year) and optionally tick the accesses under Accounts (none selected = all): — none ticked means: all.
3. Create token. The token appears only now (Visible only now:) — Copy token and store it safely.
4. In the other program send the token in the header of every request: Authorization: Bearer bda_… — for example curl -H "Authorization: Bearer bda_…" https://<your-relay>/admin/api/devices?tenant=<access>.

How to use in the same dialog gives the details. To revoke: Revoke in the list — it takes effect at once.

Set up a webhook

1. Support › Tickets → tab Settings → Integration (with several accesses, choose the access at the top).
2. Tick Integration active.
3. Enter the Webhook URL and create a Webhook secret with Generate secret. The value appears once in plain text — copy it into your system.
4. Or fetch instead of a webhook: Generate key for the API key (pull); your system then calls GET /api/events?after=<number> with the header X-BD-Api-Key.
5. Save integration.

How you know it worked

• Token: the list shows the token with Valid until and Last used. A request with the token returns data instead of a refusal; whatever the token changes appears in the audit log under api:<name> (G17).
• Webhook: for a new ticket a POST arrives at your address with the headers X-BD-Event, X-BD-Event-Id and X-BD-Signature: sha256=… (HMAC-SHA256 of the body with your secret).

Good to know

• Role at most Supervisor: a token never manages users, tokens, accesses or the relay's configuration. Valid for at most 365 days.
• Treat it like a password: the relay does not store the token in readable form; whoever has it works with its role.
• Not for the remote console: an API token does not open a command line on a device.
• "SCIM provisioning" only applies to user management via SCIM, not to the console API (B4).
• Events: ticket.created, ticket.status, ticket.note, session.started, session.ended, plus device.alert and device.alert.cleared (only alert rules with the "Webhook" box ticked). Receivers must be able to skip unknown events.
• Opening a session from the PSA works without a token via a link: https://<your-relay>/app/?tenant=<access>&id=<device-id>&ticket=<number>.
• Cloud: API tokens for your access cannot be created yourself yet — write to info@browserdesk.de. Webhook and fetching work with the ticket system booked.
• A way back (the PSA changing tickets in BrowserDesk) and an OpenAPI description do not exist yet.
• The console's English label for the accesses of a token is "Accounts" — it means the accesses (tenants).

If it does not work