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

# Escopos

> Configure permissões granulares no seu token da Ticto API v2. Veja quais escopos cada endpoint exige e como lidar com erros de escopo insuficiente.

Escopos definem exatamente o que um token pode fazer. Ao criar um token, você escolhe um conjunto de escopos, e o token só pode acessar os endpoints cobertos por essas permissões. Essa granularidade segue o **princípio de menor privilégio**: um token que só precisa ler produtos nunca deve ter permissão para criá-los. Isso limita o raio de impacto em caso de vazamento e facilita a auditoria de acessos.

## Escopos disponíveis

| Escopo | Permissão |
| - | - |
| `products:read` | Listar e visualizar seus produtos |
| `products:write` | Criar produtos |
| `offers:read` | Listar e visualizar ofertas dos seus produtos |
| `offers:write` | Criar ofertas |
| `orders:read` | Listar, resumir e visualizar seus pedidos |
| `subscriptions:read` | Listar, resumir e visualizar suas assinaturas |
| `subscriptions:cancel` | **Cancelar assinaturas.** Destrutivo e irreversível |
| `cashouts:read` | Listar, resumir e visualizar seus saques (dado financeiro) |

<Note>
  `cashouts:read` dá acesso a dado financeiro (saques). Conceda-o apenas a tokens que realmente precisem, de preferência em um token separado dos demais.
</Note>

<Warning>
  `subscriptions:cancel` é o único escopo destrutivo da API: ele cancela assinaturas de verdade, e não há como desfazer.

  Por isso ele é tratado de forma diferente dos demais:

  * **Nunca vem junto.** Um token com escopo amplo não recebe `subscriptions:cancel` por tabela. Ele precisa ser pedido nominalmente na criação do token.
  * **Limites próprios.** A rota de cancelamento aceita 5 requisições por minuto e 50 por dia, bem abaixo do resto da API.
  * **Proteção contra varredura.** Um token que acumula respostas `404` nessa rota (tentando `id` que não existe ou não é seu) é bloqueado temporariamente nela.

  Recomendação: mantenha o cancelamento em um token separado, usado só por esse fluxo.
</Warning>

## Quais escopos cada endpoint exige

| Endpoint | Método | Escopo obrigatório |
| - | - | - |
| `/products` | `GET` | `products:read` |
| `/products/{hash}` | `GET` | `products:read` |
| `/products` | `POST` | `products:write` |
| `/products/{hash}/offers` | `GET` | `offers:read` |
| `/products/{hash}/offers/{code}` | `GET` | `offers:read` |
| `/products/{hash}/offers` | `POST` | `offers:write` |
| `/orders/history` · `/orders/summary` · `/orders/{hash}` | `GET` | `orders:read` |
| `/subscriptions/history` · `/subscriptions/summary` · `/subscriptions/{id}` | `GET` | `subscriptions:read` |
| `/subscriptions/{id}/cancel` | `POST` | `subscriptions:cancel` |
| `/cashouts/history` · `/cashouts/summary` · `/cashouts/{id}` | `GET` | `cashouts:read` |

<Tip>
  Crie tokens separados para leitura e escrita. Se o token de leitura vazar, sua conta não corre risco de criação fraudulenta de produtos, ele simplesmente não tem essa permissão.
</Tip>

## Erro de escopo insuficiente

Quando um token válido tenta acessar um endpoint para o qual não possui o escopo necessário, a API retorna `403 Forbidden` com o seguinte corpo:

```json theme={null}
{
  "error": "insufficient_scope",
  "message": "Token is missing the required ability: orders:read.",
  "request_id": "req_xxx"
}
```

Para corrigir, verifique quais escopos o endpoint exige (tabela acima) e gere um novo token com as permissões adequadas, ou adicione o escopo ao token existente no painel em **Integrações → API v2**.


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