Chaves de API

A API REST do Pliic é autenticada com chaves secretas (sk_live_…), uma por app. Cada chave carrega um conjunto de escopos que limitam o que ela pode acessar.

A API está disponível nos planos Starter e Pro. O plano Gratuito não inclui este recurso.

Onde gerenciar

Acesse Configurações → Chaves de API. A página lista cada app da equipe com a sua chave secreta, os escopos atuais, o último uso e o status (ativa ou revogada).

Apenas membros com papel Administrador ou Dono podem visualizar e gerenciar as chaves de API.

Escopos

Os escopos definem quais partes da API a chave pode usar:

Escopo	Permite
`suggestions:read`	Ler sugestões
`suggestions:write`	Criar e atualizar sugestões
`tickets:read`	Ler tickets de suporte
`tickets:write`	Criar e atualizar tickets
`analytics:read`	Ler dados de analytics
`privacy:read`	Exportar dados de privacidade do usuário
`privacy:write`	Excluir dados de privacidade do usuário

Selecione Acesso total para conceder todos os escopos atuais e futuros.

Toda chave nova nasce somente leitura

Quando um app é criado, a chave secreta vem com suggestions:read e tickets:read, mais nada. É proposital: a chave só ganha permissão de escrita quando alguém decide conceder. Ou seja, a primeira requisição de escrita da sua integração (POST /api/v1/suggestions, POST /api/v1/tickets) falha até você marcar o escopo de escrita aqui.

Erro de escopo insuficiente

Quando a chave é válida mas não tem o escopo que o endpoint exige, a resposta é 403 com este corpo:

{
    "message": "This API key is not allowed to perform this request: it is missing the \"tickets:write\" scope. …",
    "error": "insufficient_scope",
    "required_scope": "tickets:write",
    "granted_scopes": ["suggestions:read", "tickets:read"],
    "manage_scopes_url": "https://pliic.com/team/sua-equipe/settings/api-keys",
    "docs_url": "https://docs.pliic.com/integrations/api-keys/"
}

error é um código estável: use ele nas suas condições, não o texto de message.
required_scope é o que falta, granted_scopes é o que a chave tem hoje.
manage_scopes_url abre direto esta tela para liberar o escopo.

O corpo do erro nunca traz a chave nem o hash dela.

Rotacionar uma chave

Em Ações da chave → Rotacionar chave, uma nova chave secreta é gerada e exibida uma única vez. Os escopos são preservados, mas a chave antiga deixa de funcionar imediatamente. Atualize suas integrações com o novo valor antes de fechar o aviso.

Revogar e restaurar

Revogar desativa a chave imediatamente: qualquer requisição passa a retornar 401. Use Restaurar para reativá-la. A chave secreta em si não muda ao revogar/restaurar.

Referência da API

O botão Referência da API abre a documentação interativa (OpenAPI) com todos os endpoints, parâmetros e exemplos. A especificação também está disponível publicamente em /api/v1/openapi.json.