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

# Autenticação

> Como funciona o token da API do Connecta DESK: formato sk_live_, header Bearer, prazo de validade, IPs autorizados e rotação.

Toda requisição à API v1 leva o token da empresa no header `Authorization`, no esquema `Bearer`:

```bash theme={null}
Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

A API não usa login, sessão nem refresh token. O token é a credencial inteira.

## O que é o token

<Columns cols={2}>
  <Card title="Pertence à empresa" icon="building">
    Ele não está ligado a nenhum usuário. Continua valendo mesmo se a pessoa que o criou sair da
    empresa, e as ações feitas com ele aparecem em nome da integração.
  </Card>

  <Card title="Carrega as próprias regras" icon="shield-check">
    Permissões por módulo e método, prazo de validade e IPs autorizados ficam no próprio token.
    Quem cria o token define até onde ele pode ir.
  </Card>
</Columns>

O valor tem o formato `sk_live_` seguido de 32 caracteres. Os primeiros caracteres formam o
**prefixo** (`sk_live_ab12cd34`), que o painel mostra na listagem para você identificar cada
token.

<Note>
  Por segurança, a chave completa aparece uma única vez, na criação, e não pode ser recuperada
  depois. Se você perder a chave, rotacione o token.
</Note>

## Usando em cada requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.connectadesk.com/api/v1/tickets?status=open" \
    --header "Authorization: Bearer $CONNECTA_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const api = (path, init = {}) =>
    fetch(`${process.env.CONNECTA_URL}${path}`, {
      ...init,
      headers: {
        Authorization: `Bearer ${process.env.CONNECTA_TOKEN}`,
        'Content-Type': 'application/json',
        ...init.headers
      }
    });

  const res = await api('/tickets?status=open');
  ```

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

  sessao = requests.Session()
  sessao.headers.update({
      "Authorization": f"Bearer {os.environ['CONNECTA_TOKEN']}",
      "Content-Type": "application/json",
  })

  res = sessao.get(f"{os.environ['CONNECTA_URL']}/tickets", params={"status": "open"})
  ```

  ```php PHP theme={null}
  $ch = curl_init(getenv('CONNECTA_URL') . '/tickets?status=open');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer ' . getenv('CONNECTA_TOKEN'),
          'Content-Type: application/json',
      ],
  ]);

  $resposta = curl_exec($ch);
  ```
</CodeGroup>

## Quando o token é recusado

Token ausente, em formato inválido, inexistente, revogado, expirado ou usado a partir de um IP não
autorizado recebem **exatamente a mesma resposta**:

```json theme={null}
{
  "error": {
    "code": "ERR_API_UNAUTHORIZED",
    "message": "Token de API ausente ou inválido."
  }
}
```

Por segurança, a API não informa qual foi o motivo da recusa.

<Tip>
  Para descobrir o motivo, consulte o painel. Ele mostra o status do token, a data de expiração,
  os IPs autorizados e o último uso (`lastUsedAt`). Se o `lastUsedAt` não mudou, a API não chegou
  a reconhecer sua requisição.
</Tip>

## Prazo de validade

O prazo é opcional e é definido na criação do token. Quando vence, o token para de funcionar na
mesma hora, sem aviso prévio e sem período de tolerância.

<Warning>
  Anote a data de expiração junto com os dados da integração. Como a resposta é o mesmo 401
  genérico, um token vencido parece um token errado, e descobrir a causa leva tempo.
</Warning>

Para trocar a chave sem recriar a integração, use **Rotacionar** no painel. O token mantém nome,
permissões e IPs autorizados e recebe um valor novo, que também aparece uma única vez. O valor
antigo deixa de valer imediatamente.

## IPs autorizados

Se a integração roda a partir de um IP fixo, restrinja o acesso. Com a lista preenchida, chamadas
de qualquer outra origem recebem o mesmo 401.

<ParamField path="Endereço único" type="IPv4">
  Libera apenas esse endereço, por exemplo `200.150.10.20`.
</ParamField>

<ParamField path="Faixa" type="CIDR">
  Libera qualquer endereço dentro da faixa, por exemplo `191.30.0.0/16`.
</ParamField>

Regras da lista:

* **Em branco, qualquer origem é aceita.** Esse é o padrão quando o campo nunca foi preenchido.
* **Até 50 entradas** por token.
* **Somente IPv4.** Endereços IPv6 não são aceitos no cadastro.
* A API considera o IP real da conexão. Por segurança, o header `X-Forwarded-For` enviado na
  requisição não altera a origem considerada.

<Warning>
  Antes de restringir uma integração que já está em produção, confirme o IP de saída real dela.
  Serviços em nuvem costumam sair por um endereço diferente do que aparece no painel do provedor,
  e uma lista errada derruba a integração na hora.
</Warning>

## Gestão dos tokens

Criar, editar, rotacionar e revogar tokens são operações feitas no **painel**, com o login de um
administrador. Por segurança, um token de API não consegue gerenciar tokens, e não existe
endpoint público para isso.

<CardGroup cols={2}>
  <Card title="Permissões" icon="shield-check" href="/essentials/permissoes">
    O que cada módulo e método libera.
  </Card>

  <Card title="Segurança do token" icon="lock" href="/guides/seguranca-do-token">
    Como escolher escopo e prazo, e o que fazer se uma chave vazar.
  </Card>
</CardGroup>


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