Autenticação

Toda requisição leva uma chave de API no cabeçalho Authorization:

Authorization: Bearer lp_live_XXXXXXXX…    (chave de espaço de trabalho)
Authorization: Bearer lpp_live_XXXXXXXX…   (chave de parceiro)

As chaves são criadas no painel, exibidas uma única vez no momento da criação e armazenadas como hash SHA-256 — ninguém, nem mesmo o suporte, consegue recuperar uma chave perdida. Perder uma chave significa revogá-la e criar outra.

Tipos de chave

• Chaves de espaço de trabalho (lp_live_…) atuam dentro de um espaço de trabalho: links, analytics, domínios, trilha de auditoria e webhooks do espaço. Criadas pelos administradores do espaço de trabalho em Configurações → Chaves de API.
• Chaves de parceiro (lpp_live_…) atuam na conta de parceiro: clientes, planos, domínios, pagamentos, repasses e webhooks de parceiro. Criadas pelos administradores do parceiro.

Uma chave de espaço de trabalho que chame /partner/* (ou o contrário) recebe 403 forbidden — as famílias de endpoints são estritamente separadas.

Escopos

Os escopos são concedidos por chave no momento da criação. Uma requisição precisa de todos os escopos exigidos pelo seu endpoint; se algum faltar, a resposta é 403 insufficient_scope indicando qual escopo está ausente.

| Escopo | Concede | |---|---| | links:read / links:write | Ler / criar, atualizar, arquivar e excluir links | | analytics:read | Resumo, séries temporais, detalhamentos, principais links, exportação CSV — e a visão geral de cliques de todo o parceiro | | domains:read / domains:write | Ler / conectar e desconectar domínios | | qr:read | Renderizar os QR codes dos links | | workspace:read | Perfil do espaço de trabalho, limites e trilha de auditoria | | webhooks:read / webhooks:write | Ler / gerenciar endpoints de webhook | | partner:read | Perfil, plano e uso do parceiro | | clients:read / clients:write | Ler / criar, alterar e suspender clientes | | plans:read / plans:write | Ler / gerenciar os planos do parceiro | | payments:read | Espelho de pagamentos e repasses |

Essa é a lista completa — quinze escopos — e uma chave só pode conter nomes dela. Os QR codes são somente leitura pela API: renderizar um exige qr:read, e não existe escopo de escrita de QR porque não existe endpoint de mutação de QR.

Há uma combinação que costuma confundir: GET /partner/analytics/overview precisa de analytics:read na chave de parceiro, e não de partner:read. Todos os endpoints de analytics usam o mesmo escopo, qualquer que seja o tipo de chave.

Dê a cada integração a sua própria chave, com os escopos mínimos necessários: uma chave para um widget de painel se resolve com links:read + analytics:read, enquanto um script de provisionamento precisa de clients:write.

Restrições por plano

O acesso à API é um recurso do plano (api_access):

• para as chaves de espaço de trabalho, tanto o plano do espaço de trabalho quanto o plano de plataforma do parceiro precisam incluir o acesso à API;
• para as chaves de parceiro, o plano de plataforma do parceiro precisa incluí-lo.

Um plano sem acesso à API responde 403 plan_restricted. Espaços de trabalho em teste, ainda sem plano, não são restringidos.

Rotação e revogação

Revogar uma chave tem efeito imediato: a requisição seguinte responde 401 unauthorized. Para fazer a rotação sem interrupção, crie primeiro a chave nova, troque a integração e só então revogue a antiga. Cada chave registra last_used_at, então uma chave antiga sem uso é fácil de identificar antes de revogá-la.

Opcionalmente, uma chave pode ter data de validade — chaves expiradas se comportam exatamente como as revogadas.

Boas práticas

• As chaves são segredos: guarde-as em um gerenciador de segredos, nunca em código do lado do cliente, repositórios ou logs.
• Uma chave por integração — revogar uma não quebra as demais, e a trilha de auditoria atribui cada alteração à chave que a fez.