Primeiros passos

Autenticação

Envie a sua chave secreta como bearer token. As chaves têm escopos e agem com a função de quem as criou em um único espaço de trabalho, no máximo como Editor.

Bearer token

Envie Authorization: Bearer sk_live_… em toda requisição. Nunca coloque uma chave em uma URL ou em um cookie; não há outro cabeçalho para ela. Uma chave ausente, malformada, revogada ou expirada responde 401 unauthorized, sem dizer qual.

Uma chave pertence a um espaço de trabalho. GET /v1/workspaces/current devolve ele e o seu plano. Se você enviar X-Workspace-Id, ele deve nomear o espaço de trabalho da chave.

Criando chaves

Crie chaves no app em Settings → API. Editores, administradores e o proprietário criam chaves que agem como eles mesmos; os administradores também podem renomear e revogar as de qualquer pessoa. Visualizadores não podem criar chaves. Um espaço de trabalho pode ter 50 chaves ativas.

O segredo é mostrado uma vez e guardamos apenas o hash dele. A API não permite chamadas entre origens pelo navegador: mantenha as chaves no seu servidor.

Escopos

Escolha os escopos ao criar a chave; eles não podem ser alterados depois (gire ou crie uma nova chave). Uma requisição precisa do escopo da rota, listado ao lado de cada rota na referência da API. Uma chave sem ele recebe 403 forbidden com details.reason missing_scope.

codes:readLista e lê códigos, suas versões e atividades; baixa arquivos; inicia e lê exportações e execuções em massa.Viewer ou superior

codes:writeCria, altera, pausa, move e exclui códigos; cria em massa; envia logos e arquivos.Editor ou superior

analytics:readEstatísticas do espaço de trabalho e de cada código, e registros de cada escaneamento.Viewer ou superior

submissions:readRespostas a formulários hospedados. Contêm dados pessoais de quem respondeu.Editor ou superior

folders:readLista e lê pastas.Viewer ou superior

folders:writeCria, renomeia, move e exclui pastas. O compartilhamento fica no app.Editor ou superior

templates:readLista e lê modelos de design.Viewer ou superior

templates:writeCria, altera e exclui modelos de design.Editor ou superior

domains:readLista os domínios personalizados e seu status, para escolher um para novos códigos.Viewer ou superior

webhooks:readLista os endpoints de webhook e suas entregas.Administrador ou superior

webhooks:writeRegistra, altera e exclui endpoints de webhook; envia um evento de teste; reenvia. Somente administradores.Administrador ou superior

tags:readLista as tags do espaço de trabalho e quantos códigos têm cada uma.Viewer ou superior

tags:writeCria, renomeia, muda a cor e exclui tags. Aplicar tags a códigos exige Codes · write.Editor ou superior

cards:readLista e lê os cartões de visita da equipe e suas estatísticas.Viewer ou superior

cards:writeCria, altera, desativa e reatribui cartões de visita. Somente administradores.Administrador ou superior

conversions:writeEnvia conversões do seu servidor (pedidos, cadastros) para o funil de escaneamentos.Editor ou superior

Funções

Uma chave nunca faz mais do que a função atual de quem a criou permite, no máximo como Editor. Se quem criou for rebaixado a visualizador, a chave perde na hora os escopos de escrita; quando quem criou sai do espaço de trabalho, as chaves dele são revogadas.

webhooks:read e webhooks:write são a exceção: só administradores e o proprietário podem concedê-los, e eles só continuam funcionando enquanto quem criou ainda for administrador.

Restrições de pasta e de IP

Uma chave pode ser limitada a até 20 pastas e suas subpastas, por exemplo uma chave por pasta de cliente. Ela então não vê nada fora delas, e uma escrita em outro lugar responde 403 com details.reason api_key_folder_restricted.

Uma chave também pode ser limitada a até 20 intervalos de IP no formato CIDR (203.0.113.0/24). Uma chamada de qualquer outro lugar responde 403 com details.reason ip_not_allowed.

Expiração e rotação

Uma chave pode expirar em uma data que você escolher. Girar uma chave emite um novo segredo com o mesmo nome, escopos e restrições; o segredo antigo continua funcionando por 24 horas por padrão (0 a 168), para você publicar o novo sem indisponibilidade. A revogação vale na hora.

O que uma chave não pode fazer

As chaves chamam apenas as rotas da referência da API. Sua conta, membros e convites, cobrança, configurações do espaço de trabalho, compartilhamento, configuração de domínios e as próprias chaves de API ficam no app: essas rotas respondem a uma chave com 403 forbidden e details.reason session_required.