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

# Token permissions

> The token is authorized per module and per method. Learn the 17 modules of the Connecta DESK API and how to set the minimum scope for each integration.

A token's permission is a **module × method** matrix. Every API route belongs to a module, and
the method is the request's HTTP verb. For a call to work, the token needs that method enabled on
that module.

```json theme={null}
{
  "contacts": ["GET", "POST"],
  "tickets": ["GET"]
}
```

This token can read and create contacts and read tickets, and nothing else. `PUT /contacts/{id}`
responds 403, as does any call to products, campaigns or CRM.

<Info>
  Permission is the last check performed. Before it, the API confirms that the token is valid, the
  company is active, the plan includes the API and the request limit has not been reached. So a
  scope 403 always means the token was valid and the call reached the right endpoint.
</Info>

## The modules

<Columns cols={2}>
  <Card title="contacts" icon="user" horizontal>
    Contacts, extra fields and marketing origin.
  </Card>

  <Card title="tickets" icon="message-square" horizontal>
    Opening, transferring, closing and wrapping up.
  </Card>

  <Card title="messages" icon="send" horizontal>
    Asynchronous sending and reading of messages.
  </Card>

  <Card title="channels" icon="smartphone" horizontal>
    Channels and templates. Read-only.
  </Card>

  <Card title="webchat" icon="messages-square" horizontal>
    Webchat visitor sessions and messages.
  </Card>

  <Card title="tags" icon="tags" horizontal>
    Tags and their link to tickets.
  </Card>

  <Card title="queues" icon="list-video" horizontal>
    Service queues and their agents.
  </Card>

  <Card title="wrapups" icon="award" horizontal>
    Wrap-up types.
  </Card>

  <Card title="users" icon="user-cog" horizontal>
    Agents, administrators and invitations.
  </Card>

  <Card title="profiles" icon="shield-check" horizontal>
    Permission profiles. Read only.
  </Card>

  <Card title="schedules" icon="calendar" horizontal>
    Scheduled messages.
  </Card>

  <Card title="quick-messages" icon="zap" horizontal>
    Quick replies.
  </Card>

  <Card title="campaigns" icon="megaphone" horizontal>
    Bulk sends and their execution.
  </Card>

  <Card title="crm" icon="kanban" horizontal>
    Boards, stages, cards and metrics.
  </Card>

  <Card title="products" icon="package" horizontal>
    Catalog, categories and performance.
  </Card>

  <Card title="custom-fields" icon="list-plus" horizontal>
    Custom fields and global variables.
  </Card>

  <Card title="reports" icon="chart-column" horizontal>
    Reports and dashboards.
  </Card>
</Columns>

The methods are `GET`, `POST`, `PUT` and `DELETE`. No v1 route uses `PATCH`, so it is not on the
list.

The `profiles` module accepts `GET` only. It exists so you can find the `profileId` used when
inviting or editing a user; profiles are created and edited in the dashboard.

The `webchat` module accepts `GET` and `POST`: with it, your system opens a visitor session, sends
the visitor's messages and reads the replies. The webchat is configured in the dashboard.

## Choosing the scope

Give the token only the permissions the integration needs to work. Some common examples:

<AccordionGroup>
  <Accordion title="External dashboard or BI" icon="chart-column">
    ```json theme={null}
    { "reports": ["GET"], "tickets": ["GET"], "contacts": ["GET"] }
    ```

    Read-only. Even if it leaks, a token like this cannot change any data, so it is a good choice
    for third-party tools.
  </Accordion>

  <Accordion title="Transactional notifications" icon="send">
    ```json theme={null}
    { "messages": ["POST"], "channels": ["GET"] }
    ```

    Enough to send messages and find the `channelId` of the outbound channel. You don't need to
    include `contacts` or `tickets`, because sending already creates the contact and the ticket
    when needed.
  </Accordion>

  <Accordion title="Record synchronization" icon="refresh-cw">
    ```json theme={null}
    { "contacts": ["GET", "POST", "PUT"], "custom-fields": ["GET"], "tags": ["GET"] }
    ```

    This scope does not include `DELETE`. If the sync has a bug and deletes contacts, the damage is
    hard to undo. If the integration needs to delete contacts, use a second token in a separate
    routine.
  </Accordion>

  <Accordion title="Board automation" icon="kanban">
    ```json theme={null}
    { "crm": ["GET", "POST", "PUT"], "contacts": ["GET"], "products": ["GET"] }
    ```

    Moves cards and records notes. Reads contacts and the catalog without being able to change
    them.
  </Accordion>
</AccordionGroup>

<Warning>
  Write permission on `users` gives administrator power. With `users: ["POST"]`, the token invites
  people to the company. With `users: ["PUT"]`, it changes the profile of people who are already
  part of it and can even promote someone to administrator. Grant these two permissions only to HR
  or provisioning integrations that really need them.
</Warning>

## When permission is missing

```json theme={null}
{
  "error": {
    "code": "ERR_API_FORBIDDEN_SCOPE",
    "message": "O token não tem permissão de POST no módulo \"contacts\"."
  }
}
```

The message tells you the method and the module that were missing. To fix it, open the token in
the panel and check that combination.

<Tip>
  The list of modules above is the same one the panel shows when you create a token. If the panel
  shows a module that is not listed here, treat the panel as the correct reference.
</Tip>

## What the token never does

Regardless of the permissions checked:

* **It does not manage tokens.** Creating, editing, rotating and revoking tokens requires an
  administrator session in the panel.
* **It does not switch companies.** The company is always the token's own. A `companyId` sent in
  the body is ignored.
* **It does not see the super admin.** The platform's support membership does not appear in
  `GET /users` and cannot be changed through the API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.