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.

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:

appointments:read, services:read, products:read, inventory:read, bank-accounts:read, projects:read, deals:read, forms:read, vehicles:read, pets:read.

Na criação, o padrão é *:read. 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/me, no campo 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. Peça a configuração ao time da Ligga quando a chave for criada.

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 rotacionar: peça uma chave nova com os mesmos escopos, troque o valor na integração e só então revogue a antiga.
• 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 é feita para chamadas de servidor. O CORS está desabilitado e nenhuma resposta traz Access-Control-Allow-Origin, então a chamada direta de um navegador falha. Se a sua aplicação roda no navegador, coloque um intermediário no seu próprio backend e chame esse intermediário.

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