Autenticação
Criar uma chave de API, enviá-la, e o que ela alcança.
Cada requisição leva uma chave de API da organização. Não há fluxo de OAuth nem login de usuário: a chave é a credencial.
Pegar uma chave
Abra Desenvolvedores
No painel, Desenvolvedores — fica no menu da esquerda, acima de Configurações. É só para Dono e Administrador.
Crie a chave
Dê um nome que diga onde ela vai rodar ("Site", "Sync do backoffice"). Esse nome é o que depois permite revogar exatamente a certa.
Escolha um vencimento
Sem vencimento, ou 30, 90, 180 dias ou um ano. Uma chave que vence é a versão barata da rotação: escolha uma data se a integração for algo que você estará por perto para renovar.
Copie agora
A chave aparece uma única vez. Guardamos um hash, não a chave, então se você perder não há o que recuperar — cria uma nova e revoga a antiga.
Uma chave de API é uma credencial completa sobre os dados da sua organização. Guarde-a num servidor, numa variável de ambiente ou num gerenciador de segredos. Nunca em código de front-end, num repositório ou num navegador: tudo que chega a um visitante chega com a chave dentro.
Como enviar
Funcionam dois cabeçalhos, e são equivalentes. Escolha um.
Se faltar ou não for válida, sai um 401:
{ "error": { "code": "API_KEY_MISSING", "message": "The API key is missing or not valid." } }O que uma chave alcança
Uma organização, inteira. A chave fica presa à organização em que foi criada, e nenhuma requisição nomeia uma organização: tudo que você lê e tudo que escreve fica dentro dela. Se você opera várias, crie uma chave por organização.
Hoje não há escopos por chave nem chave somente leitura. Toda chave pode fazer tudo o que a API faz, o que hoje significa: ler a operação, e escrever clientes e produtos do catálogo.
Uma chave não é uma pessoa. Ela não carrega função e não é afetada pelas políticas da agência: essas limitam o que um integrante vê no painel, e uma chave não é um integrante. O que uma chave lê é a organização inteira.
Revogar
Na mesma tela de Desenvolvedores. Revogar tem efeito imediato, e é o que fazer diante de qualquer suspeita de que uma chave vazou: não há janela de rotação para esperar e nada mais quebra, porque as chaves são independentes entre si.
Por isso o nome também importa: com uma chave por integração você revoga a que vazou em vez de derrubar tudo junto.
Acompanhar o uso
Desenvolvedores → Atividade mostra as requisições que as suas chaves fazem: quais endpoints, com que status voltaram e quanto demoraram. É a forma mais rápida de distinguir "minha integração está quebrada" de "minha integração não está chamando".