Agent SDK Segredos e HMAC Assinatura
Proteja as credenciais do Agente API e compreenda como o SDK gera assinaturas de pedido HMAC-SHA256 com carimbo de data e hora e resistentes à reprodução.
Os pedidos Agent SDK são autenticados com um segredo do parceiro API. Mantenha este segredo dentro de um serviço de back-end fiável e deixe que o SDK gere campos de subscrição sempre que possível.
Dois protocolos de assinatura
A assinatura Agent SDK utiliza campos de pedido classificados, um carimbo de data/hora baseado em segundos e um nonce. Os pedidos diretos Developer API utilizam o processo separado descrito em Solicitar assinatura. Não reutilize um formato de carga útil para o outro.
Regra de assinatura
Para pedidos Agent SDK:
- Apague o campo
sign. - Omita campos com valores vazios.
- Ordene os restantes nomes dos campos pela ordem ASCII.
- Junte os campos como
k=v&k2=v2. - Calcule a assinatura hexadecimal HMAC-SHA256 com
apiSecret.
Os valores da matriz são serializados como compactos JSON antes de se juntarem à carga útil de assinatura. Por exemplo, platformUserIds assina como ["1188041528"], fornecendo platformUserIds=["1188041528"] na carga útil k=v. Preservar a ordem dos elementos do array, as aspas duplas e os IDs de string; não introduza espaços de formatação nem utilize Java List.toString() (como [1188041528]). O SDK trata esta serialização automaticamente.
O SDK deve construir este valor a partir dos mesmos dados que envia. A alteração de um campo assinado após a geração da assinatura provoca a falha da verificação.
Campos geridos por SDK
Armazenamento secreto
- Carregue
apiSecreta partir de um gestor de segredos de back-end ou de uma configuração de tempo de execução protegida. - Nunca coloque o segredo em pacotes de front-end, aplicações móveis, clientes de desktop, capturas de ecrã ou tickets de suporte.
- Mantenha as credenciais de desenvolvimento, preparação e produção separadas.
- Limite o acesso aos serviços e operadores que dele necessitem.
- Edite as assinaturas de pedidos, os valores de autorização e os segredos dos registos.
- Revogar e substituir as credenciais quando haja suspeita de exposição.
Proteção de relógio e replay
O SDK inclui timestamp e nonce para reduzir o risco de repetição. Mantenha os relógios de back-end sincronizados e não reutilize um nonce construído manualmente. Se a validação da assinatura falhar, confirme o segredo configurado, a hora do servidor, os campos serializados e o ambiente antes de tentar novamente.