Autenticação

A Ligga API usa chaves de API estáticas, enviadas no cabeçalho Authorization: Bearer …. Não há fluxo OAuth nem renovação automática: a chave é um segredo de longa duração, sob controle da conta que a criou.

Gestão de chaves da equipe

No portal Ligga, acesse Configurações → API e confira a equipe selecionada. A aba depende da liberação do contrato e de permissão de administrador; usuários comuns e gerentes não podem administrar chaves.

• Nova chave: informe o nome da integração, as permissões necessárias e uma data de expiração, ou escolha explicitamente uma chave sem expiração.
• Editar: ajuste nome, permissões, expiração e restrição de IP conforme os recursos disponíveis para o contrato.
• Rotacionar: gera uma nova chave e revoga a anterior na mesma operação. Prepare a atualização da integração antes de confirmar: a chave antiga deixa de funcionar imediatamente.
• Revogar: interrompe imediatamente o acesso daquela chave. Essa ação não pode ser desfeita.

A listagem mostra somente um identificador mascarado, estado, datas e último uso. O segredo completo aparece uma única vez na criação ou rotação; guarde-o no cofre de segredos da integração. Ao fechar a janela ou trocar de equipe, o valor deixa de ser exibido. Se uma falha de conexão impedir o recebimento, confira a listagem e revogue a chave cujo segredo foi perdido antes de emitir outra. Não há recuperação do valor original.

A gestão segue o limite de chaves ativas do contrato. Uma chave expirada ou revogada não pode ser reativada. A liberação da aba não habilita módulos ou permissões comerciais adicionais.

Formato da chave

ligga_live_…    produção
ligga_test_…    modo teste

• O prefixo indica o ambiente: ligga_live_ para produção, ligga_test_ para modo teste.
• Depois do prefixo vêm 34 caracteres base62: 28 aleatórios mais 6 de checksum CRC32. O checksum permite validar o formato sem consultar a Ligga e reconhecer chaves vazadas em varreduras de código.
• A parte aleatória carrega cerca de 166 bits de entropia.
• A chave é gerada no servidor e exibida uma única vez, na criação. A Ligga guarda apenas o SHA-256: uma chave perdida não pode ser recuperada, só substituída.
• Os quatro últimos caracteres ficam disponíveis para identificar a chave sem expor o valor. É o que GET /v1/me devolve em key_last4.
• Chaves v1, com corpo de 32 caracteres e sem checksum, emitidas antes de julho de 2026, continuam válidas.

Cuidado

As chaves ligga_test_ não apontam para um ambiente isolado: elas leem e escrevem no mesmo banco de produção. Um POST com chave de teste cria um registro real. Veja Modo teste.

Como autenticar

Toda requisição carrega o cabeçalho:

Authorization: Bearer ligga_live_…

Nos exemplos deste site, a chave vem de uma variável de ambiente:

export LIGGA_API_KEY='ligga_live_…'
export LIGGA_BASE='https://api.ligga.app/functions/v1/api'

curl "$LIGGA_BASE/v1/me" \
  -H "Authorization: Bearer $LIGGA_API_KEY"

Escopos

Cada chave carrega uma lista de escopos, verificada endpoint a endpoint. O escopo tem a forma <recurso>:read ou <recurso>:write, onde o recurso é o mesmo segmento que aparece na rota, em kebab-case: bank-accounts:read, nunca bank_accounts:read.

O que cada escopo concede

Escopo	Concede
<recurso>:read	Leitura daquele recurso
<recurso>:write	Escrita e leitura daquele recurso
*:read	Leitura de todos os recursos, sem nenhuma escrita
*:write	Escrita e leitura de todos os recursos

Escrita implica leitura, no recurso e no coringa. Uma chave com sales:write lê e escreve em Vendas sem precisar de sales:read. Uma chave com *:write cobre a API inteira sozinha, sem precisar de *:read ao lado. O contrário não vale: *:read não concede nenhuma escrita.

Escopos de leitura e escrita

Estes recursos aceitam os dois escopos:

• customers:read, customers:write
• sales:read, sales:write
• suppliers:read, suppliers:write
• expenses:read, expenses:write

Escopos somente de leitura

Nestes recursos existe apenas o escopo de leitura:

services:read, products:read, inventory:read, bank-accounts:read, wallets:read, credit-cards:read, card-machines:read, me:read, team:read, contract:read e users:read.

Agenda usa calendars:read / calendars:write e appointments:read / appointments:write.

Na aba API, selecione explicitamente as permissões necessárias. Chaves antigas podem ter escopos coringa (*); antes de substituí-las, edite suas permissões e escolha os recursos disponíveis no contrato. Não existe escopo administrativo: cobrança, gestão de usuários e mudança de plano não são expostas na API.

Nota

O escopo não substitui o módulo. Além do escopo da chave, cada recurso depende de um módulo do Monte seu Plano estar habilitado no contrato da conta. Uma chave com sales:read em uma conta sem o módulo vendas recebe 403 module_not_enabled. Os módulos ativos aparecem em GET /v1/team, no campo data.api.modules. Veja Módulos e escopos.

Restrição por IP

Uma chave pode carregar uma lista de IPs permitidos. Com a lista configurada, requisições vindas de qualquer outro endereço recebem 403 ip_not_allowed. Administradores podem configurar essa restrição na aba API. Informe IPs individuais; intervalos CIDR não são aceitos.

Expiração e rotação

• A data de expiração é opcional. Sem data, a chave não expira.
• Chaves sem uso por 180 dias são sinalizadas para revisão. Nenhuma revogação acontece automaticamente.
• Para trocar uma chave sem interrupção, crie uma segunda chave se houver espaço no limite, atualize a integração e revogue a anterior. A ação Substituir chave da aba API revoga a anterior imediatamente.
• A revogação é imediata, sem período de tolerância. A chave revogada passa a responder 401 token_revoked.
• Mesmo sem incidente, rotacione as chaves uma vez por ano.

CORS

A API destina-se a integrações de servidor. O CORS permite origens oficiais específicas, incluindo este portal de documentação para testar requisições. Isso não torna seguro incluir uma chave em um site público: seus visitantes poderiam copiá-la. Para uma aplicação de navegador, mantenha a chave no seu backend e faça as chamadas por ele.

A gestão de chaves em portal.ligga.app usa a sessão do administrador e uma superfície própria; uma chave de integração não pode criar outras chaves.

Boas práticas

• Guarde a chave em um cofre de segredos, nunca no repositório.
• Use uma chave por integração. Assim um incidente isola uma integração só, e o tráfego de cada uma fica identificável.
• Use ligga_test_ em desenvolvimento e homologação e reserve ligga_live_ para produção.
• Não coloque a chave em aplicação de navegador, aplicativo móvel, repositório público ou registro de log.

Erros de autenticação

O campo type do corpo do erro é a URL https://api.ligga.app/errors/ seguida do código abaixo.

HTTP	type	Quando acontece
401	invalid_token	Cabeçalho Authorization ausente, formato inválido ou chave inexistente
401	token_revoked	A chave foi revogada
401	token_expired	A chave passou da data de expiração
403	insufficient_scope	A chave é válida, mas não carrega o escopo que o endpoint exige
403	api_disabled	A conta ainda não tem a API habilitada
403	module_not_enabled	O recurso depende de um módulo fora do contrato da conta
403	ip_not_allowed	A chave restringe IPs e a requisição veio de fora da lista

Veja também

• Início rápido — a primeira chamada, passo a passo
• Módulos e escopos — qual módulo cada recurso exige
• Modo teste — o que ligga_test_ faz hoje
• Erros — o catálogo completo e o formato do corpo