TerramineDESKTalk to our team

Documentation / Set-up guides / For developers

API keys and webhooks

On this page
This guide is for

Other systems reach this workspace through its API: service keys that carry scopes, a REST API under /api/v1, and signed events. The page opens for the workspace's owner with an administrator role.

This is the hosted workspace API. Send service keys with Authorization: Bearer. Its two business events are crm.deal.stage_changed and quote.sent. Failed deliveries have no twelve-hour automatic retry loop. An admin can replay rejected, expired or settled-not-sent deliveries after checking the receiver; unknown outcomes require reconciliation before retrying.
  1. Open Admin → Integrations → Integrations. The page shows the Workspace URL every call goes to, with links to the quickstart, the agent guide and the changelog.
  2. Create a service key. Give it a name, tick the scopes, tick the box that authorises access to the workspace's records of those kinds, and press Create key. The secret is shown once: save it in your integration's secret store before you dismiss it.
  3. Check the first call. Paste a key that has customers:read and press Look up customers.
  4. Receive signed events. Choose the key, the event and the Receiver URL, and press Create subscription. Each subscription has a signing secret of its own.
  5. Press Send synthetic test. It sends a signed test event that carries no business record: the receiver should verify it and acknowledge it, and create nothing.
  • The scopes offered: crm:read, crm:write, customers:read, orders:read, orders:write and documents:read. A scope whose module is off is refused.
  • The events: a deal's stage changed, and a quotation sent.
  • Delivery history shows the latest 100 deliveries, with Retry delivery. Rotate replaces a key's secret; Revoke stops the key.
  • The contract your workspace runs is at /api/v1/openapi.json on the workspace's own address.

For every other system, and for n8n, Make or Power Automate, the desk has an API of its own: keys that carry scopes, a REST API under /api/v1, and signed webhooks.

This is the API for your own deployment. It accepts Authorization: Bearer or X-API-Key, offers seven business webhook events, and retries failed deliveries for twelve hours. Hosted workspaces use a separate API contract.

Making a key

  1. Open Admin → Integrations → Connections → Desk open API.
  2. Under API keys, press New key. In What uses it, name the system that will hold the key, and tick the scopes it may use: a key carries its scopes and nothing else.
  3. Press Make the key and copy it at once. It is shown this once and kept only as a hash.
  4. Send it with every call, in the header Authorization: Bearer or X-API-Key.
  • The reference — every address, its scope and its parameters — is at /api/erp/open-api/docs on your desk, for anyone signed in.
  • Every call is logged with its key. Revoke stops a key at once.

Webhooks

  1. Under Webhooks, press New webhook. Enter Their address, which must start with https://, tick the events it receives, and press Add the webhook.
  2. Copy the signing secret at once. It is shown this once.
  3. Check every delivery on the receiving side. The header X-Desk-Signature carries t, the time, and v1, the HMAC-SHA256 of the time, a full stop and the raw body, made with the signing secret.
  • The events: order.created, order.updated, quote.sent, proforma.sent, invoice.sent, purchase_order.updated and payment.received.
  • A delivery that fails is tried again for twelve hours. Deliveries lists each one, with Send again.
  • Pause and Resume stop and restart a webhook without losing it.