Escopos

Cada endpoint exige um escopo. Se a key não tiver o escopo necessário, a API responde 403 com insufficient_scope.

Escopo	Permite
`tickets:read`	Ler tickets, mensagens, comentários, anexos e histórico
`tickets:write`	Criar e atualizar tickets, responder e comentar
`customers:read`	Ler clientes, departamentos e clientes finais
`customers:write`	Criar e atualizar clientes, departamentos e clientes finais
`kb:read`	Ler artigos da base de conhecimento
`kb:write`	Criar e atualizar artigos da base de conhecimento
`agile:read`	Ler projetos, sprints, boards, épicos e tasks
`agile:write`	Criar e atualizar sprints, boards, épicos e tasks
`analytics:read`	Ler dashboards e métricas (tickets e Agile)

:write não inclui :read. Uma integração que cria e consulta tickets precisa de tickets:read e tickets:write.

Presets no painel

Integração	Escopos
Abrir tickets a partir de um formulário	`tickets:write`
Sincronizar clientes com CRM	`customers:read`, `customers:write`
Painel de BI	`analytics:read`
Agente de IA de triagem (MCP)	`tickets:read`, `tickets:write`, `kb:read`
Agente de IA de gestão ágil (MCP)	`agile:read`, `agile:write`, `analytics:read`

Os endpoints do Agile também exigem que a empresa tenha o ambiente Agile habilitado. Sem ele, a API responde 403, mesmo com o escopo.

Por segurança, a API pública não expõe exclusões. Para arquivar uma task, use POST /v1/tasks/{id}/archive.