KEPLIN Docs

APIs & GraphQL Chaves de API

Chaves de API

Gerar, delimitar e revogar API keys — o acesso dos sistemas externos ao GraphQL das tuas apps.

Os sistemas externos — um ERP que sincroniza clientes, um site que cria pedidos, uma integração de facturação — chamam o GraphQL das apps com uma API key: um segredo enviado no header x-api-key de cada pedido. As keys são geridas ao nível da plataforma e partilhadas entre apps: cada key tem um scope — escolhes as apps e, por app, todos os endpoints ou só alguns. Uma integração de facturação pode, por exemplo, ler contas na app Gestão de Clientes e escrever documentos noutra app, com uma única key.

Nota

As keys são de quem administra a plataforma: a página API Keys só está disponível a contas de administrador.

A página API Keys

Abre o menu API Keys na navegação global. A lista mostra todas as keys da plataforma:

Coluna O que é
Nome O nome que deste à key — identifica a integração.
Prefixo Os primeiros caracteres da chave (ex. amk_A1b2C3…) — servem para reconheceres qual é qual sem nunca mostrar a chave inteira.
Scope As apps a que dá acesso e, por app, "todos os endpoints" ou a lista dos concedidos.
Estado activa ou revogada.
Última utilização Quando a key foi usada pela última vez — nunca, se ainda não foi.

A página API Keys, com o scope e a última utilização de cada key.
A página API Keys, com o scope e a última utilização de cada key.

Dica

A coluna Última utilização é a tua ferramenta de limpeza: uma key com meses sem uso é candidata a revogação.

Criar uma API key

  1. Carrega em Nova API key.
  2. Dá um Nome da key — ex. integração-faturação.
  3. Em Scope — apps e endpoints permitidos, marca as apps a incluir. Por omissão, cada app marcada concede "Todos os endpoints desta app."
  4. Para apertar o acesso numa app, marca Restringir a endpoints específicos e escolhe as APIs uma a uma. Numa API de Tabela, o grant cobre todas as operações activas — a lista mostra "dá acesso a: getContas, addContas, …" para saberes exactamente o que concedes.
  5. Carrega em Gerar API key.

O modal de criação de uma API key, com o scope por app e endpoint.
O modal de criação de uma API key, com o scope por app e endpoint.

Copiar e guardar a chave

Depois de gerar, a janela mostra a Chave em texto claro — uma única vez. Copia-a com Copiar e guarda-a num sítio seguro (um gestor de segredos, o cofre da tua equipa). Quando fechares a janela já não a voltas a ver — a plataforma não guarda a chave em claro; se a perderes, só poderás revogá-la e gerar outra.

A chave gerada, em texto claro pela única vez, com o botão Copiar.
A chave gerada, em texto claro pela única vez, com o botão Copiar.

Atenção

Trata a chave como uma password: não a metas em código-fonte, nem em URLs, nem em ecrãs de utilizador. Se suspeitares de fuga, revoga já — gerar uma key nova custa segundos.

Usar a chave

A chave segue no header x-api-key de cada pedido ao endpoint GraphQL da app:

curl -X POST 'https://o-teu-host/api/graphql/gestao-clientes' \
  -H 'content-type: application/json' \
  -H 'x-api-key: amk_………' \
  -d '{"query":"query { getContas(take: 5) { id nome } }"}'

O separador Docs de cada API gera este exemplo (e a variante JavaScript) já com a operação certa — só falta a tua chave.

O que uma key vê e não vê:

  • Só APIs publicadas — rascunhos nunca, mesmo com scope de app inteira.
  • Só o que o scope concede: chamar uma app fora do scope devolve 403 — API key not authorised for this project; chamar um endpoint fora do scope, 403 — API key not authorised for this endpoint.
  • Sempre a versão principal da app (ou a versão publicada do endereço usado) — nunca a versão de trabalho de um developer.

Limites e erros

Cada key tem um tecto de pedidos por minuto. As respostas de erro que uma integração deve saber tratar:

Resposta Significado O que fazer
401 Key em falta, inválida, expirada ou revogada. Verifica o header e o estado da key na lista.
403 Key válida mas sem acesso à app ou ao endpoint. Ajusta o scope — gera uma key nova com o scope certo.
429 Tecto de pedidos por minuto atingido. Espera o tempo indicado no header retry-after e repete.

Revogar uma key

  1. Na lista, carrega no ícone de revogar da linha.
  2. Confirma em Revogar key.

A revogação é imediata: todas as apps consumidoras desta key perdem acesso no pedido seguinte. Uma key revogada não pode ser reactivada — fica na lista, marcada revogada, como registo.

Porque não…?

  • Perdi a chave — posso vê-la outra vez? Não. A chave em claro só é mostrada no momento da criação. Revoga a antiga e gera outra.
  • Preciso de dar acesso a mais um endpoint — edito a key? O scope define-se na criação. Gera uma key nova com o scope completo, troca-a na integração e revoga a antiga.
  • Porque recebe a integração 403 num endpoint novo? A key foi restringida a endpoints específicos e o novo não está na lista — o mesmo remédio: key nova com o scope certo.
  • A key dá acesso aos ecrãs da app? Não. Uma key só fala com o endpoint GraphQL. As contas de utilizadores da app são outra coisa, geridas nas definições da própria app.