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

# Autenticação

> Guia completo de autenticação via OAuth2 + PKCE para as APIs Zipdin

# Autenticação

Todas as APIs Zipdin utilizam autenticação via **OAuth2** com tokens JWT (Bearer). Dependendo do tipo de integração, você utilizará um dos fluxos abaixo.

## Fluxos Disponíveis

<Tabs>
  <Tab title="Client Credentials (M2M)">
    Para integrações **server-to-server** sem interação do usuário.

    ```bash theme={null}
    POST /oauth/token
    Content-Type: application/x-www-form-urlencoded

    grant_type=client_credentials
    client_id=SEU_CLIENT_ID
    client_secret=SEU_CLIENT_SECRET
    scope=api
    ```

    **Quando usar:** Backends, jobs, pipelines de dados, integrações automatizadas.
  </Tab>

  <Tab title="Authorization Code + PKCE">
    Para aplicações **frontend** ou **mobile** onde o usuário faz login interativo.

    **Passo 1 — Redirecionar para autorização:**

    ```
    GET /oauth/authorize?
      response_type=code
      &client_id=SEU_CLIENT_ID
      &redirect_uri=https://seuapp.com/callback
      &scope=api+profile
      &code_challenge=CHALLENGE_BASE64
      &code_challenge_method=S256
    ```

    **Passo 2 — Trocar code por token:**

    ```bash theme={null}
    POST /oauth/token
    Content-Type: application/x-www-form-urlencoded

    grant_type=authorization_code
    code=CODIGO_RECEBIDO
    redirect_uri=https://seuapp.com/callback
    client_id=SEU_CLIENT_ID
    code_verifier=VERIFIER_ORIGINAL
    ```

    **Quando usar:** Portais web, apps mobile, SPAs.
  </Tab>
</Tabs>

## Estrutura do Token

O token JWT retornado contém as seguintes claims:

| Claim    | Descrição                                |
| -------- | ---------------------------------------- |
| `sub`    | Identificador do usuário ou client       |
| `iss`    | Issuer (servidor de autenticação Zipdin) |
| `exp`    | Timestamp de expiração (Unix)            |
| `scope`  | Escopos concedidos                       |
| `tenant` | Código da conveniada/parceiro            |

## Usando o Token

Inclua o token no header `Authorization` de todas as requisições:

```bash theme={null}
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```

<Warning>
  Tokens expiram em **1 hora** (3600 segundos). Implemente refresh automático
  para evitar interrupções na integração.
</Warning>

## Refresh Token

Para fluxos com `refresh_token`, renove o acesso sem reautenticação:

```bash theme={null}
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token=SEU_REFRESH_TOKEN
client_id=SEU_CLIENT_ID
```

## Escopos Disponíveis

| Escopo     | Descrição                  | Acesso            |
| ---------- | -------------------------- | ----------------- |
| `api`      | Acesso geral às APIs       | Leitura e escrita |
| `api:read` | Somente leitura            | Consultas         |
| `profile`  | Dados do perfil do usuário | Login interativo  |
| `admin`    | Operações administrativas  | Restrito          |

## Erros de Autenticação

Para o catálogo completo de erros de todas as APIs, veja o guia de [Tratamento de Erros](/guides/error-handling). Abaixo, os erros específicos do fluxo de autenticação:

| HTTP Status | Código               | Descrição                          |
| :---------: | -------------------- | ---------------------------------- |
|     401     | `invalid_token`      | Token expirado ou inválido         |
|     401     | `missing_token`      | Header Authorization ausente       |
|     403     | `insufficient_scope` | Token não possui escopo necessário |
|     429     | `rate_limited`       | Muitas tentativas de autenticação  |

<Tip>
  Em **homologação**, você pode testar todo o fluxo de integração com dados
  fictícios antes de migrar para produção.
</Tip>