Autenticação

Cada integrador recebe uma credencial própria. Não há registo automático: a credencial é emitida pela empresa de condomínios com quem vai trabalhar, com as áreas que lhe forem concedidas.

Como se apresenta

Em todos os pedidos, no cabeçalho ApiKey:

curl https://servidor.exemplo/api/integrations/v1/acme/buildings \
  -H "ApiKey: gcik_XXXXXXXXXXXXXXXXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"

A credencial começa sempre por gcik_. Para além disso é opaca: trate-a como texto, não a parta nem lhe atribua significado.

A credencial é um segredo

Nunca a coloque em código do lado do cliente, em aplicações móveis, em repositórios ou em URLs. Quem a tiver faz tudo o que a sua integração faz. Guarde-a como guardaria uma palavra-passe de base de dados.

Só é mostrada uma vez

No momento da emissão. A partir daí a empresa já não consegue consultá-la — se a perder, a única saída é revogar a antiga e emitir uma nova. Guarde-a antes de fechar a janela onde a recebeu.

Validade

A credencial pode ser emitida com data de expiração ou sem ela. Se tiver, a API começa a responder KEY_EXPIRED a partir dessa data — sem período de tolerância.

Peça uma credencial nova antes da data de expiração e mude a configuração quando a tiver: as duas não coexistem, e trocar depois de expirar significa integração parada.

Rotação

Para substituir uma credencial sem interrupção, peça a nova, ponha-a a funcionar, confirme com o ping, e só depois peça a revogação da antiga.

Quando corre mal

Todas as falhas de autenticação trazem um código que diz o que fazer:

Estado	Código	O que significa	O que fazer
401	INVALID_KEY	O cabeçalho ApiKey falta, está malformado, ou não corresponde a nenhuma credencial conhecida	Verifique o cabeçalho e a empresa no caminho
401	KEY_REVOKED	A credencial foi revogada	Peça uma nova
401	KEY_EXPIRED	A credencial ultrapassou a data de validade	Peça uma nova
403	FORBIDDEN_SCOPE	A credencial é válida mas não lhe foi concedida a área deste pedido	Peça o alargamento da permissão. Ver Permissões

{
  "Error": {
    "Code": "INVALID_KEY",
    "Message": "The ApiKey header is missing or does not match a known credential.",
    "Field": null
  }
}

401 e 403 não são a mesma coisa

401 é um problema com a credencial. 403 é uma credencial boa a tentar uma área que não lhe foi concedida — não vale a pena renová-la. A distinção existe precisamente para não andar a perseguir um problema de chave que não existe.

Uma empresa desconhecida responde INVALID_KEY, tal como uma chave errada. É intencional: se o erro fosse distinto, o caminho passava a permitir descobrir que empresas existem.

Quem fica registado

Cada pedido deixa registo de qual credencial o fez e com que resultado terminou. É o que permite à empresa responder a "quem alterou isto" e a nós ajudar em suporte. Uma razão a mais para cada integrador ter a sua chave e não partilhar nenhuma.