Chaves de API e tokens de acesso

Uma chave de API é a forma de os seus programas entrarem na API do LinkHarbor. Pertence a um espaço de trabalho, não a uma pessoa, e pode fazer exatamente o que lhe permitir através dos scopes. Para as chamadas propriamente ditas, troca a chave por um token de acesso de curta duração.

#Quem pode criar chaves de API?

• Proprietários e admins do espaço de trabalho – editores e leitores só veem o cartão «Apps ligadas» em «Callback e API»
• A partir do Creator Pro; no Creator Free, o cartão indica «As chaves de API estão disponíveis a partir do Creator Pro.»
• Ativas em simultâneo: até 5 chaves no Creator Pro, até 20 no Creator Agency, até 50 no Enterprise

Quando o limite é atingido, a criação de uma chave falha com 409 limit_reached. Elimine primeiro uma chave de que já não precise.

#Criar uma chave de API

1. Abra «Callback e API» no menu
2. No cartão «Chaves de API», clique em «+ Criar nova chave»
3. Em «Nome (opcional)», introduza um nome pelo qual reconheça a chave mais tarde, por exemplo «Pipeline de CI/CD» ou «Sincronização da loja»
4. Em «Scopes», escolha «Leitura» ou «Escrita» para cada área
5. Clique em «Criar chave»
6. Copie de imediato o «Segredo da chave (privado)» e guarde-o num local seguro
7. Feche a caixa de diálogo – o ID da chave está sempre disponível na lista

«Nome (opcional)»

Até 64 caracteres. Sem nome, a chave aparece na lista como «Chave de API #ID».

«Scopes»

É obrigatório pelo menos um. «Escrita» inclui automaticamente «Leitura» para a mesma área. Estatísticas e pagamentos de apoiantes são só de leitura, os modelos do espaço de trabalho só de escrita. Todos os scopes estão explicados em Scopes em pormenor.

«Segredo da chave (privado)»

Começa por lt_ e é mostrado exatamente uma vez («⚠️ Só é visível uma vez — copie agora!»). O LinkHarbor guarda apenas um hash do segredo e não o pode voltar a mostrar mais tarde.

«ID da chave:»

16 caracteres formados por algarismos e pelas letras maiúsculas A–F, por exemplo 6F668EA6598B0692. Não é secreto e aparece na lista com um botão de copiar.

#A lista de chaves

Cada chave ativa mostra o nome, o estado «Ativa», o ID da chave, os scopes, «Criada:» e «Última utilização:» ou «Ainda não utilizada». A hora da última utilização é atualizada em cada chamada feita com a chave, no máximo uma vez por minuto. «↺ Atualizar» recarrega a lista.

#Trocar a chave por um token de acesso

curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'

{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }

token

O token de acesso. Envia-o em cada pedido como Authorization: Bearer <token>.

expires_in

Validade em segundos: 900, ou seja, 15 minutos. Não existe refresh token – quando expira, basta obter um novo token com o ID e o segredo da chave.

O token representa o espaço de trabalho e tem exatamente os scopes da chave. Não tem uma função como uma pessoa: os endpoints que o painel reserva a proprietários e admins (membros, faturação, gestão de domínios, webhooks, definições do espaço de trabalho) são sempre recusados para tokens de chaves de API. As exceções são os links curtos e os modelos do espaço de trabalho, que funcionam com o scope correspondente, e a leitura dos segredos de callback (sem o segredo em texto simples) com read:workspaces.

#Tentativas falhadas e bloqueio

Com api_key_locked, o tempo restante está em details.retry_after_sec. Uma troca bem-sucedida repõe o contador a zero.

#Eliminar e substituir uma chave

1. Clique em «Eliminar» junto à chave
2. Escreva DELETE para confirmar
3. Clique em «Eliminar de forma permanente»

A chave deixa de funcionar de imediato – os tokens de acesso já emitidos também deixam de funcionar a partir desse momento e recebem 401 invalid_token. Não existe botão para rodar a chave. Para mudar de chave, crie uma nova, passe o seu programa para ela e depois elimine a antiga.

#Quando o plano desce

Se o espaço de trabalho passar para o Creator Free, todas as chaves de API são revogadas. Se passar para um plano com menos chaves, as mais recentes mantêm-se e as restantes são revogadas. As chaves revogadas não voltam com um upgrade posterior – nessa altura, cria chaves novas. Os proprietários recebem um e-mail com a lista das funcionalidades desativadas. Mais informações em Cancelamento e downgrade.

#Manter a chave em segurança

• Guarde o segredo apenas num gestor de segredos ou em variáveis de ambiente, nunca no código-fonte nem num repositório Git
• Nunca o use em código que corre no browser ou numa app no dispositivo do utilizador
• Crie uma chave separada para cada aplicação, com o menor número possível de scopes
• Elimine de imediato as chaves de que já não precisa
• Se suspeitar de uma fuga: elimine a chave e crie uma nova