Autenticação

Todos os endpoints da Public API usam OAuth 2.0 com Authorization: Bearer <access_token>.

Escopos Base

Escopo	Uso
`openid`	Identifica o usuário que autorizou a integração.
`profile`	Permite consultar dados básicos do usuário.
`email`	Permite consultar o e-mail do usuário.
`offline_access`	Permite emissão de refresh_token.

Os escopos base não liberam acesso aos recursos da API. Para acessar clientes, tickets, contratos etc., o token precisa conter os escopos de entidade abaixo.

Regra Geral dos CRUDs

Para quase todas as entidades, a regra é:

Operação	Escopo necessário
GET listagem	`<entidade>:read`
GET detalhe	`<entidade>:read`
POST criação	`<entidade>:write`
PATCH atualização	`<entidade>:write`
DELETE exclusão	`<entidade>:delete`

Escopos por Entidade

Entidade	Endpoints	Ler	Criar/Editar	Excluir
Clientes	`/clients`, `/clients/{clientId}`	`clients:read`	`clients:write`	`clients:delete`
Contatos	`/clients/{clientId}/contacts`	`contacts:read`	`contacts:write`	`contacts:delete`
Tickets	`/clients/{clientId}/tickets`	`tickets:read`	`tickets:write`	`tickets:delete`
Oportunidades	`/clients/{clientId}/opportunities`	`opportunities:read`	`opportunities:write`	`opportunities:delete`
Tarefas	`/clients/{clientId}/tasks`	`tasks:read`	`tasks:write`	`tasks:delete`
Planos de sucesso	`/clients/{clientId}/success-plans`	`success-plans:read`	`success-plans:write`	`success-plans:delete`
Objetivos de planos de sucesso	`/clients/{clientId}/success-plans/{successPlanId}/objectives`	`success-plans:read`	`success-plans:write`	`success-plans:delete`
Tarefas de objetivos	`/clients/{clientId}/success-plans/{successPlanId}/objectives/{objectiveId}/tasks`	`tasks:read`	`tasks:write`	`tasks:delete`
Contratos	`/clients/{clientId}/contracts`	`contracts:read`	`contracts:write`	`contracts:delete`
Alterações de contrato	`/clients/{clientId}/contracts/{contractId}/changes`	`contracts:read`	`contracts:write`	`contracts:delete`
Cobranças	`/clients/{clientId}/charges`	`charges:read`	`charges:write`	`charges:delete`
Recebimentos	`/clients/{clientId}/receivables`	`receivables:read`	`receivables:write`	`receivables:delete`
Health scores	`/clients/{clientId}/health-scores`	`health-scores:read`	`health-scores:write`	`health-scores:delete`
Eventos de analytics	`/clients/{clientId}/analytics-events`	`analytics-events:read`	`analytics-events:write`	`analytics-events:delete`

Exemplos

Listar clientes

GET /api/public/v1/clients
Authorization: Bearer <access_token>

Escopo necessário: clients:read

Criar ticket de um cliente

POST /api/public/v1/clients/{clientId}/tickets
Authorization: Bearer <access_token>

Escopo necessário: tickets:write

Criar alteração de contrato

POST /api/public/v1/clients/{clientId}/contracts/{contractId}/changes
Authorization: Bearer <access_token>

Escopo necessário: contracts:write

Endpoints OAuth

Estes endpoints fazem parte do fluxo de autenticação e não usam os escopos de entidade:

Endpoint	Uso
`GET /api/public/v1/oauth/authorize`	Inicia autorização da integração.
`POST /api/public/v1/oauth/token`	Troca code ou refresh_token por tokens.
`POST /api/public/v1/oauth/revoke`	Revoga token.
`POST /api/public/v1/oauth/introspect`	Consulta metadados de um token.
`GET /api/public/v1/oauth/userinfo`	Retorna dados do usuário autorizado.
`GET /api/public/v1/oauth/.well-known/openid-configuration`	Metadados OIDC.
`GET /api/public/v1/oauth/.well-known/oauth-authorization-server`	Metadados OAuth.
`GET /api/public/v1/oauth/jwks`	Chaves públicas do provedor.