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

# First call

> Create a token in the Connecta DESK panel and make your first authenticated request to the v1 API.

By the end of this page you will have a valid token and a real response from the API. You will
create the token in the panel and call a read endpoint.

## Before you start

<Info>
  Only company **administrators** can create tokens. If the **Integrations** menu does not show up
  in the settings, ask whoever manages the account for the token.
</Info>

The base URL is `https://api.connectadesk.com/api/v1`. If your company uses its own installation,
replace it with that domain and keep the `/api/v1` at the end.

<Steps>
  <Step title="Create the token in the panel">
    Go to **Settings → Integrations → API** and click **New token**. Fill in the fields:

    * **Name**: how you will recognize the token in the list. Use the name of the system that will
      use the API, not something like "token 1".
    * **Permissions**: check only the modules and methods the integration needs. An external
      report, for example, only needs `GET`.
    * **Expiry**: set an expiry date whenever the integration is temporary.
    * **Allowed IPs**: if the system that will call the API has a fixed IP, restrict access to
      it. If left blank, the API accepts calls from any origin.

    <Warning>
      The full key appears **only once**, when the token is created. After that the panel shows
      only the prefix (`sk_live_ab12cd34…`). If you lose the key, there is no way to recover it.
      In that case, rotate the token.
    </Warning>
  </Step>

  <Step title="Keep the key outside the code">
    ```bash theme={null}
    export CONNECTA_TOKEN="sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
    export CONNECTA_URL="https://api.connectadesk.com/api/v1"
    ```

    The key gives access to the whole company's data, within the permissions you checked. Treat
    the key like a password and never put it in a repository, a log or the front-end.
  </Step>

  <Step title="Make the call">
    List the company's contacts. Since it is a `GET`, nothing is changed, and the call confirms
    that the token, the host and the permission are correct.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url "$CONNECTA_URL/contacts?perPage=2" \
        --header "Authorization: Bearer $CONNECTA_TOKEN"
      ```

      ```javascript Node.js theme={null}
      const res = await fetch(`${process.env.CONNECTA_URL}/contacts?perPage=2`, {
        headers: { Authorization: `Bearer ${process.env.CONNECTA_TOKEN}` }
      });

      const { data, meta } = await res.json();
      console.log(data, meta);
      ```

      ```python Python theme={null}
      import os, requests

      res = requests.get(
          f"{os.environ['CONNECTA_URL']}/contacts",
          params={"perPage": 2},
          headers={"Authorization": f"Bearer {os.environ['CONNECTA_TOKEN']}"},
      )

      print(res.json())
      ```

      ```php PHP theme={null}
      $ch = curl_init(getenv('CONNECTA_URL') . '/contacts?perPage=2');
      curl_setopt_array($ch, [
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONNECTA_TOKEN')],
      ]);

      echo curl_exec($ch);
      ```
    </CodeGroup>
  </Step>

  <Step title="Read the response">
    ```json theme={null}
    {
      "data": [
        {
          "id": 1042,
          "name": "Marina Alves",
          "number": "5511999999999",
          "email": "marina@exemplo.com.br",
          "isGroup": false,
          "tags": [{ "id": 3, "name": "Customer", "color": "#22C55E" }]
        },
        {
          "id": 1043,
          "name": "Rafael Nunes",
          "number": "5521988888888",
          "email": null,
          "isGroup": false,
          "tags": []
        }
      ],
      "meta": { "page": 1, "perPage": 2, "hasMore": true }
    }
    ```

    Records always come in `data`. On lists, `meta` tells you the current page and whether there
    are more records. The response **does not include `total`**. To go through everything,
    advance `page` while `hasMore` is `true`.
  </Step>
</Steps>

## If the response was not 200

<AccordionGroup>
  <Accordion title="401 ERR_API_UNAUTHORIZED" icon="lock">
    The API returns the same 401 for a token that is missing, malformed, nonexistent, revoked,
    expired or used from an IP that is not among the allowed ones. For security reasons, the
    response does not say what the reason was.

    Check, in this order: whether the header is in the `Authorization: Bearer sk_live_…` format;
    whether the token is revoked or expired in the panel; and, if you set up allowed IPs, whether
    the call is coming from the expected IP.
  </Accordion>

  <Accordion title="403 ERR_API_FORBIDDEN_SCOPE" icon="shield-x">
    The token is valid, but it does not have permission for that method on that module. The error
    message tells you which combination was missing. Edit the token's permissions in the panel.
    See [Permissions](/en/essentials/permissoes).
  </Accordion>

  <Accordion title="403 ERR_API_NOT_ENABLED" icon="ban">
    The company's plan does not include the public API. Talk to the sales team, because there is
    nothing to fix in the integration.
  </Accordion>

  <Accordion title="404 on everything" icon="link-2-off">
    The cause is almost always the base URL without `/api/v1` or the wrong host. The API returns
    the 404 in the same error envelope as the other responses (`ERR_API_ROUTE_NOT_FOUND`). If the
    body of the 404 came back as HTML, your call did not reach the API.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Send a message" icon="send" href="/en/guides/enviar-mensagens">
    The full asynchronous flow, from the `202` to the confirmation that the message was sent.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/en/essentials/erros">
    The error envelope and what each code means.
  </Card>

  <Card title="Idempotency" icon="repeat" href="/en/essentials/idempotencia">
    How to repeat a call without duplicating the effect.
  </Card>

  <Card title="Reference" icon="code" href="/en/api-reference/introduction">
    Every endpoint, with a playground to test in the browser.
  </Card>
</CardGroup>


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