Get early access
In this section (10)

Build an integration with OAuth

Register an OAuth client so users of any ChaosDesk workspace can approve your app, and manage the apps people approved.

3 min read

If you build an integration that other ChaosDesk customers will use, register it as an OAuth client. Users then approve your app on a consent screen, and it calls the API as that user, with only the access they approved, in their workspace only. No one has to copy an API token.

For your own scripts, an API token is simpler.

ChaosDesk uses the same OAuth paths as Zendesk, so a Zendesk OAuth integration keeps working after you change the host.

Register a client

  1. Open Admin Center, Integrations, API tokens and find OAuth clients.
  2. Choose Register OAuth client.
  3. Fill in the Name, Company, Website and Description. Users see them on the consent screen.
  4. Enter the Redirect URIs, one per line: https:// addresses, http://127.0.0.1 for native apps, or a reverse-domain scheme such as com.example.app:/callback. They must match exactly: no wildcards.
  5. Pick the Client type:
    • Confidential: a server-side app that can keep a secret. You get a client secret, shown once.
    • Public: a mobile, desktop or browser app without a secret.
  6. Choose Register and copy the Client ID (and secret).

The client belongs to your workspace, but users of every workspace can approve it. Only your workspace can change, disable or delete it.

  • New secret replaces the client secret. The old one stops working at once.
  • Disable or Delete ends every token the app holds, in every workspace.

How users connect your app

Your app sends the user to their workspace’s authorization page. They sign in if needed and see the consent screen: your app’s name and company, and what it will be able to do. They choose Allow or Deny.

After Allow, your app receives a code and exchanges it for an access token (valid 2 hours) and a refresh token (valid 30 days).

For developers: the flow

  1. Send the user to https://{workspace}.chaosdesk.io/oauth/authorizations/new with response_type=code, client_id, redirect_uri, scope, state, and a PKCE code_challenge with code_challenge_method=S256.
  2. On Allow, the user returns to your redirect_uri with code and state. On Deny, you get error=access_denied.
  3. Within 10 minutes, exchange the code once at POST https://{workspace}.chaosdesk.io/oauth/tokens with grant_type=authorization_code, the code, redirect_uri, client_id, code_verifier and, for confidential clients, the client_secret.
  4. Call the API with Authorization: Bearer <access_token>, on the REST API or the Zendesk-compatible API.
  5. Refresh with grant_type=refresh_token. Each refresh returns a new pair and ends the old one. Reusing an old refresh token ends the whole chain.

To revoke a token from your app, call POST /oauth/revoke with the token and your client credentials.

Codes and tokens only work in the workspace that issued them.

Scopes

  • read: read tickets, users, organizations and other data the user can see.
  • write: read and change what the user can change.
  • Per resource, such as tickets, users, organizations, groups, help centre, macros, triggers, views and webhooks, each with read or write.
  • admin: change admin settings. Only an admin can grant it.

An app never gets more access than the user who approved it. Whatever the scopes, apps can’t reach API tokens, OAuth clients, sign-in and account settings, or data exports.

Remove an app’s access

Admin Center, Integrations, API tokens, Authorized apps lists the apps people approved for this workspace, who approved them, the scopes and when they were last used. Agents see their own apps; admins see everyone’s.

Choose Remove access to revoke the app’s tokens at once. It has to be approved again to get access back.

Was this article helpful?