Permissões

Uma credencial não dá acesso a tudo. Cada uma é emitida com um conjunto de áreas, e um pedido fora delas responde 403 FORBIDDEN_SCOPE.

As áreas são de risco, não de rota: quem emite a credencial responde a "este parceiro pode ver os contactos dos condóminos? pode escrever? pode enviar mensagens em nome do condomínio?" — e não a quinze perguntas sobre caminhos.

As áreas

Área	Dá acesso a
masterdata:read	Condomínios, frações, fornecedores, contratos de manutenção, apólices de seguro, tabelas de referência, lista de destinatários de atribuição, contas de despesa, rubricas e contas de pagamento dos condomínios
people:read	Condóminos de uma fração e procura de pessoas por email ou telefone
occurrences:read	Ocorrências e sinistros: listagem, detalhe, histórico, anexos e sincronização incremental
occurrences:write	Abrir ocorrências e sinistros, atribuir, registar intervenções, alterar estado e prioridade
finance:read	Faturas de fornecedor e pagamentos a fornecedores
finance:write	Registar faturas e pagamentos, incluindo faturação de consumos
expenses:write	Registar despesas pagas diretamente pelo condomínio, em caixa ou pelo banco, sem fatura de fornecedor
correspondence:read	Correspondência de uma fração
correspondence:send	Enviar mensagens em nome da empresa
calendar:read	Calendários e marcações
calendar:write	Criar, alterar e apagar marcações
commercial:write	Submeter propostas comerciais

Peça o mínimo

Peça apenas as áreas de que precisa. Não é burocracia: uma credencial que só lê ocorrências não pode ser usada para enviar mensagens em nome do condomínio se for comprometida, e isso é uma diferença real para o cliente final.

Se mais tarde precisar de mais, o alargamento é um pedido — não obriga a trocar de credencial nem a alterar código.

people:read e correspondence:send merecem atenção

A primeira dá acesso a dados pessoais de condóminos. A segunda permite enviar mensagens que chegam aos condóminos em nome da empresa de condomínios. Ambas costumam exigir justificação de quem as concede.

Saber o que tem

O ping devolve as áreas da credencial em uso:

{
  "Scopes": ["masterdata:read", "occurrences:read", "occurrences:write"]
}

Vale a pena verificá-lo no arranque e falhar cedo com uma mensagem clara, em vez de descobrir a falta de permissão a meio de um fluxo, num 403 que o utilizador final não percebe.

Quando falta

{
  "Error": {
    "Code": "FORBIDDEN_SCOPE",
    "Message": "This credential was not granted the occurrences:write area.",
    "Field": null
  }
}

A mensagem nomeia a área em falta — é o que deve pedir.