Chaves de API

Chave de API é como toda requisição servidor-a-servidor na Orbita Pay se autentica. Esta página é para quem administra as chaves da conta — se você só quer usar uma chave, veja Primeiros passos.

#Formato da chave

text

lq_live_<24-bytes-base64url>      ← produção
lq_test_<24-bytes-base64url>      ← teste

O texto em claro aparece exatamente uma vez, na emissão.
Do nosso lado guardamos só o fingerprint SHA-256 e um prefixo de 12 caracteres (ex.: lq_live_xyz) para exibir no painel.
Perdeu a chave? Não dá para recuperar — gire para emitir uma nova.

#Autenticação — estes endpoints usam JWT, não chave de API

Todos os endpoints /v1/api-keys/* são autenticados por JWT (o mesmo token de login do painel, devolvido por POST /v1/auth/login). Eles não passam pela autenticação por chave — seria um problema do ovo e da galinha.

text

Authorization: Bearer <JWT do painel>

A claim de conta do JWT limita toda operação — você só administra as chaves da sua própria conta.

#Endpoints

#Emitir uma chave

text

POST /v1/api-keys

bash

curl -X POST https://liqfy.com.br/v1/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "label": "backend-producao", "test": false }'

Campo	Tipo	Obrigatório	Descrição
`label`	string	não	Texto livre, até 64 caracteres. Aparece no painel, para gente ler.
`test`	booleano	não	`true` emite uma chave `lq_test_…`. Padrão `false`.

Resposta 201 Created

json

{
  "id": "5b3a9c1d-...",
  "apiKey": "lq_live_F8A2K7M3N9PQRSTUVWXYZAB",
  "fingerprint": "9a3f7e1c5d8b2a40",
  "prefix": "lq_live_F8A",
  "label": "backend-producao",
  "createdAt": "2026-04-25T18:32:11.000Z"
}

O apiKey só aparece aqui. Guarde num cofre de segredos na hora. O painel não mostra de novo nos acessos seguintes.

#Listar suas chaves

text

GET /v1/api-keys

Devolve só metadado — nunca o texto em claro.

json

{
  "data": [
    {
      "id": "5b3a9c1d-...",
      "prefix": "lq_live_F8A",
      "label": "backend-producao",
      "createdAt": "2026-04-25T18:32:11.000Z"
    },
    {
      "id": "7f1c4e9a-...",
      "prefix": "lq_test_QRX",
      "label": "testes-ci",
      "createdAt": "2026-04-12T09:14:08.000Z"
    }
  ]
}

#Girar uma chave

text

POST /v1/api-keys/{id}/rotate

Revoga a chave indicada e emite uma nova, de forma atômica. Faça isso com regularidade (a cada 90 dias é razoável) ou sempre que suspeitar de vazamento.

bash

curl -X POST https://liqfy.com.br/v1/api-keys/5b3a9c1d-.../rotate \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "label": "backend-producao (girada em 2026-04-25)" }'

O formato da resposta é idêntico ao de emitir — incluindo o novo texto em claro.

Atenção operacional: a chave antiga para de funcionar no instante em que essa chamada termina. Não existe janela de sobreposição. Ou você faz o deploy da chave nova nos seus servidores antes de chamar o rotate, ou emite uma chave paralela primeiro e revoga a antiga depois que a nova estiver no ar.

#Revogar uma chave

text

DELETE /v1/api-keys/{id}

Permanente — não tem desfazer.

bash

curl -X DELETE https://liqfy.com.br/v1/api-keys/5b3a9c1d-... \
  -H "Authorization: Bearer $JWT"

Resposta 200 OK

json

{ "revoked": true }

#Checklist de segurança

Trate lq_live_… como senha — nunca commite, nunca logue, nunca cole no chat.
Guarde num cofre de segredos (Vault, 1Password, AWS Secrets Manager, variáveis de CI…).
Chaves diferentes por ambiente (lq_live_… em produção, lq_test_… em homologação e CI).
Uma chave por serviço, ou por máquina de desenvolvedor — assim revogar uma que vazou não derruba o resto.
Gire com agenda. Trimestral no mínimo; mensal em carga sensível.
Revogue na hora quando alguém sai da equipe.
Configure alerta nos eventos de auditoria de "chave emitida" e "chave girada".

#O que fica guardado onde

Onde	O que tem lá
Gateway (autenticação)	A chave em claro — usada para autenticar as requisições que chegam.
Banco Orbita Pay	Referência da conta, para busca reversa. Nunca o texto em claro.
Log de auditoria	Eventos de emissão, rotação e revogação, com o id de quem fez e o fingerprint da chave.
Painel	Só o prefixo e o rótulo.

#Dúvidas

P: Posso ter várias chaves de produção ao mesmo tempo? R: Pode — é justamente o que permite girar sem downtime e isolar por serviço. Não há limite rígido.

P: Perdi o texto em claro logo depois de criar. R: Ele se foi. Gire (ou revogue e emita outra) — não existe caminho de recuperação, por decisão de projeto.

P: Como sei qual chave fez qual requisição? R: O log de requisições do painel mostra o fingerprint da chave em toda chamada. Filtre por ele para atribuir o tráfego.

P: Dá para restringir uma chave a certos endpoints ou métodos? R: Ainda não. Escopo por chave está no roteiro. Hoje toda chave tem acesso completo à conta.