> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messagedesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> The MessageDesk Developer API uses OAuth 2.0. How integrations obtain a token, how to send it, and what a 401 or 403 means.

# Authentication

The Developer API uses **OAuth 2.0**. Every request carries an access token in the `Authorization` header:

```http theme={null}
Authorization: Bearer eyJraWQiOiJ...
```

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.

<Note>
  **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.
</Note>

***

## 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.

<Steps>
  <Step title="Connect your account">
    In the integration provider, choose MessageDesk and click **Sign in**. The provider opens the MessageDesk authorization page.
  </Step>

  <Step title="Sign in and approve">
    Sign in with your MessageDesk credentials or Google single sign-on. Approving sends an authorization code back to the provider.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Token lifetime

| Token             | Lifetime |
| ----------------- | -------- |
| **Access token**  | 24 hours |
| **Refresh token** | 30 days  |

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](mailto:support@messagedesk.com).

Send the **access token** as the bearer token. ID tokens and refresh tokens aren't accepted.

***

## When authentication fails

| Status  | Body                                            | What it means                                                                                          |
| ------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **401** | `{"error": "Authorization header is required"}` | The header is missing.                                                                                 |
| **401** | `{"error": "<parse error>"}`                    | The token is malformed or expired.                                                                     |
| **403** | `{"error": "..."}`                              | The token is valid, but the user isn't a member of the requested workspace or lacks the required role. |

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](/settings/workspace-settings/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](/developer/api-reference/endpoints/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**.