Agent SDK Segredos e HMAC Assinatura
Proteja as credenciais do Agente API e entenda como o SDK gera assinaturas de solicitação HMAC-SHA256 com carimbo de data e hora e resistentes à reprodução.
As solicitações Agent SDK são autenticadas com um segredo do parceiro API. Mantenha esse segredo dentro de um serviço de back-end confiável e deixe o SDK gerar campos de assinatura sempre que possível.
Dois protocolos de assinatura
A assinatura Agent SDK usa campos de solicitação classificados, um carimbo de data/hora baseado em segundos e um nonce. Solicitações diretas Developer API usam o processo separado descrito em Solicitar assinatura. Não reutilize um formato de carga útil para o outro.
Regra de assinatura
Para solicitações Agent SDK:
- Exclua o campo
sign. - Omita campos com valores vazios.
- Classifique os nomes de campos restantes na 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 ingressar na 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, aspas duplas e IDs de string; não insira espaços de formatação nem use Java List.toString() (como [1188041528]). O SDK lida com essa serialização automaticamente.
O SDK deve construir esse valor a partir dos mesmos dados que envia. Alterar um campo assinado após a geração da assinatura causa falha na verificação.
Campos gerenciados por SDK
Armazenamento secreto
- Carregue
apiSecretde um gerenciador 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, aplicativos móveis, clientes de desktop, capturas de tela ou tíquetes de suporte.
- Mantenha as credenciais de desenvolvimento, preparação e produção separadas.
- Limite o acesso aos serviços e operadoras que o necessitam.
- Edite assinaturas de solicitação, valores de autorização e segredos dos logs.
- Revogar e substituir credenciais quando houver 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.