Começar

Autenticação

Como se autentica uma integração, o ciclo de vida de uma chave e o que fazer em cada falha.

Cada pedido leva a chave de API no cabeçalho X-Api-Key. Não há sessões nem tokens a renovar: a chave vale até expirar ou ser revogada.

http
GET /api/clientes HTTP/1.1
Host: <endereço-da-API>
X-Api-Key: <a-sua-chave>

#A chave

  • Pertence a uma empresa. Uma chave só chega aos dados da empresa onde foi criada; nunca aos de outra.
  • Tem um perfil. Actua com as permissões de um perfil escolhido ao criá-la (e nunca com mais).
  • Tem um titular. A pessoa que a criou: a chave actua em nome dela. Se essa pessoa deixar de estar activa, a chave deixa de funcionar até outro administrador assumir a titularidade.
  • É opaca. Trate-a como uma palavra-passe: não tente interpretá-la nem guardá-la em texto simples em repositórios.
  • Só se vê uma vez. O sistema guarda apenas uma impressão do segredo. Perdida, a chave não se recupera: crie outra.

#Ciclo de vida e erros

SituaçãoHTTPcodigoO que fazer
Sem credencial401NAO_AUTENTICADOEnviar o cabeçalho X-Api-Key.
Chave mal formada, inexistente ou de outra empresa401CHAVE_INVALIDAConferir o segredo; se perdeu, criar uma chave nova.
Chave revogada401CHAVE_REVOGADAPedir uma chave nova ao administrador da empresa.
Chave expirada401CHAVE_EXPIRADAPedir uma chave nova (ou criar, se tem permissão).
O titular já não está activo401CHAVE_SEM_TITULAR_ACTIVOUm administrador assume a titularidade em Definições › Chaves de API: o segredo mantém-se.
Pedido de um endereço fora da lista da chave403ORIGEM_NAO_PERMITIDAUsar a chave a partir de um endereço permitido, ou acrescentá-lo à chave.
A empresa está suspensa403CONTA_SUSPENSARegularizar a subscrição; a resposta indica o motivo.

Uma chave inválida

Pedido
curl 'https://<endereço-da-API>/api/clientes' \
  -H 'X-Api-Key: assw_v1_01a12201f43b731d8b555b4fef36a59a_BahhsfTZuwUWJdxtgqMV6elNHx4Z06B7BylB3AAAAAA'
Pedido
const resposta = await fetch('https://<endereço-da-API>/api/clientes', {
  method: 'GET',
  headers: {
    "X-Api-Key": "assw_v1_01a12201f43b731d8b555b4fef36a59a_BahhsfTZuwUWJdxtgqMV6elNHx4Z06B7BylB3AAAAAA"
  },
})
const dados = await resposta.json()
Pedido
import requests

resposta = requests.get(
    'https://<endereço-da-API>/api/clientes',
    headers={
        'X-Api-Key': 'assw_v1_01a12201f43b731d8b555b4fef36a59a_BahhsfTZuwUWJdxtgqMV6elNHx4Z06B7BylB3AAAAAA'
    },
)
dados = resposta.json()
Pedido
using var cliente = new HttpClient { BaseAddress = new Uri("https://<endereço-da-API>") };
using var pedido = new HttpRequestMessage(HttpMethod.Get, "/api/clientes");
pedido.Headers.Add("X-Api-Key", "assw_v1_01a12201f43b731d8b555b4fef36a59a_BahhsfTZuwUWJdxtgqMV6elNHx4Z06B7BylB3AAAAAA");
using var resposta = await cliente.SendAsync(pedido);
var texto = await resposta.Content.ReadAsStringAsync();

401 Unauthorized Resposta

Resposta
content-type: application/problem+json
x-mucanda-api-version: 1
www-authenticate: ApiKey realm="mucanda"

{
  "status": 401,
  "title": "Não autenticado",
  "detail": "Chave de API inválida.",
  "codigo": "CHAVE_INVALIDA",
  "traceId": "00-71a5884af5e330228a88b801678ed93e-bd451f3ecf90fe5b-01"
}

#Rodar uma chave sem interromper

  1. 1
    Crie a chave nova

    Com o mesmo perfil. Duas chaves válidas ao mesmo tempo é normal.

  2. 2
    Troque-a no seu sistema

    Configure a nova chave na integração e reinicie-a.

  3. 3
    Confirme o uso

    Em Chaves de API, a coluna «Último uso» da chave nova passa a mostrar actividade.

  4. 4
    Revogue a antiga

    A revogação tem efeito no pedido seguinte.