Skip to content
Kyloth

Connect an API client and signed webhooks

Limit credentials to the work an integration needs and make retries repeat the original request.

Approved preview
These instructions are for users with approved preview access. Reading them does not enable a workspace or open public signup. Check each guide for current limits.

Where: Desk, Settings, API access

  1. An owner or admin creates a named API key with only the required read or create permissions and an expiry. Copy the one-time secret into your integration's secure configuration; it cannot be revealed after closing.
  2. Expiry follows server time. If a key has expired, replace it with a permitted new expiry and update your integration; changing your device clock cannot extend access.
  3. Open OpenAPI specification from API access. Use that contract on the supplied Desk origin for contact, lead and case fields, pagination and errors. Reading the specification does not authorize an API operation.
  4. Use the key as a Bearer token with the matching permission. For creation, send a UUID Idempotency-Key with the JSON request. Keep both the UUID and content unchanged when retrying an uncertain response.
  5. A successful create or exact retry returns the original record ID. Changing content under the same key returns a conflict; a new key starts a new operation. Creating a case sends no email and grants no portal access.
  6. For webhooks, save a public HTTPS receiver in Webhooks and copy its one-time signing secret. Arrange signature verification and stable-event-ID deduplication at the receiver before asking your preview operator to activate delivery.
Before you continue
Saving a webhook endpoint does not activate its delivery worker. Every endpoint save replaces the signing secret and blocks queued deliveries for the old configuration. Inspect the confirmation before saving, then update the receiver. Events contain record IDs and lifecycle information, not full messages or contact details.

Replace creates a new API secret and stops the old one; update your integration immediately. Revoke permanently stops that key. Removing or demoting the issuing manager also disables their keys. For a permission change, issue a correctly scoped key and revoke the old one after updating the client. Staff cannot manage these credentials.