Skip to main content

​
Authentication

The Developer API uses OAuth 2.0. Every request carries an access token in the Authorization header:
MessageDesk is the OAuth 2.0 provider. A token identifies a MessageDesk user, and each request is authorized against the workspaces that user belongs to. A token can only read or write what that person can already see in the app.
Integrations run as the user who connected them. If that user loses access to a workspace, every automation built on their connection stops working for that workspace. Connect integrations with an account you expect to keep.

​
How an integration gets a token

Integration providers use the OAuth 2.0 authorization-code flow. You never see or handle the token; the provider does the exchange.
1

Connect your account

In the integration provider, choose MessageDesk and click Sign in. The provider opens the MessageDesk authorization page.
2

Sign in and approve

Sign in with your MessageDesk credentials or Google single sign-on. Approving sends an authorization code back to the provider.
3

The provider exchanges the code

The provider trades the code for an access token and a refresh token and stores both with the connection. Every request it makes sends the access token as the bearer token.
4

Tokens refresh automatically

When the access token expires, the provider uses the refresh token to get a new one. If the refresh token has expired too, the connection needs to be re-authorized and you sign in again.

​
Token lifetime

A connection that goes unused for more than 30 days has to be re-authorized. A password reset on the MessageDesk account can revoke it sooner.

​
Calling the API directly

The same authorization-code flow (with PKCE for public clients) is how any application would obtain a token. Application registration isn’t self-service yet. To register an application and receive the authorization endpoint and client ID, email support. Send the access token as the bearer token. ID tokens and refresh tokens aren’t accepted.

​
When authentication fails

A 401 from a connected integration means its connection needs to be re-authorized. Reconnect the MessageDesk account in the provider.

​
Who can connect an integration

The Developer feature permission gates integration authentication. The user who connects needs Editor or Owner on the Developer feature in the workspace. Admins have it by default. See Developer Tools for the role table and how to grant it.

​
Workspace scoping

A user may belong to several workspaces. Integrations call List my workspaces first so you can pick one, then send that workspace’s ID as id in every action body and as workspaceId on lookups. Passing a workspace the user doesn’t belong to returns 403.