Modos de autenticação

Cada rota do contrato declara como quer ser autenticada. Não é preferência: o modo escolhido reflete quem legitimamente chama aquela rota — o servidor do jogo, o comprador logado, o client na máquina do jogador — e que credencial prova essa identidade. Escolher o header errado é a causa mais comum de 401 inesperado, então vale entender o mapa antes de assinar a primeira chamada.

Para o dono de servidor que só quer a intuição: a Lootfy distingue três tipos de quem chama. O seu servidor, que é a autoridade e assina tudo. O comprador, uma pessoa logada no portal com login e senha. E o client do jogo, que roda na máquina do jogador e é território hostil — por isso ele nunca carrega uma chave secreta, só transporta envelopes que o servidor já assinou.

Os headers em jogo

São três credenciais possíveis, e um modo pode exigir uma, outra ou a combinação de duas.

Header	Credencial	Quem a possui
Authorization: Bearer <token>	JWT de sessão	O usuário logado no portal (comprador, gestor, admin).
X-Service-Api-Key: <chave>	API key do servidor	O servidor de jogo, guardada no lado dele.
X-Lootfy-Signature: <protected>..<sig>	JWS RS256 destacado	Assinado pela chave privada do servidor; o corpo é assinado, o header carrega a assinatura.

Segredos sempre viram placeholders

Em nenhum exemplo do portal aparece uma chave real. Use <sua-chave>, Bearer <token>, sk_.... A chave privada de assinatura do parceiro é entregue uma única vez e nunca fica com a Lootfy — ela guarda só a pública.

Os seis modos

public

Sem credencial nenhuma. São as rotas de entrada — login, registro, refresh de token, e o preview de um link de vínculo. Corpo inválido em rota pública responde 400 normalmente, porque não há identidade a checar antes.

bearer-only

Exige Authorization: Bearer <token>, o JWT de uma sessão de usuário logado no portal web da Lootfy. É o modo das ações que uma pessoa faz pelo navegador — o comprador pagando no checkout, o gestor configurando o servidor, o usuário cuidando do perfil e do recebimento. Nenhuma dessas é uma chamada que o seu servidor de jogo faz: do lado da integração, o seu servidor usa sempre service-only ou signature-only. O modo bearer está aqui só para você reconhecer que aquelas telas existem e são de outra superfície.

client-only

Exige X-Client-Api-Key, uma chave de client. É um modo reservado a chamadas que nascem no aplicativo cliente autenticado por chave própria, distinto da API key de servidor. Nenhuma rota do fluxo de integração de servidor de jogo usa este modo hoje — ele está no contrato, mas o seu servidor não o toca.

service-only

Exige a identidade do servidor: X-Service-Api-Key mais a assinatura JWS em X-Lootfy-Signature. A API key diz qual servidor está falando; a assinatura prova que a chamada é dele e não foi adulterada. É o modo da maioria das rotas servidor→plataforma: abrir vínculo, ajustar/retirar anúncio, consultar elegibilidade, consultar transação, confirmar entrega e reportar falha. Aqui o jti do envelope é um nonce: novo a cada tentativa, e repetir um já visto responde 401 "Requisição já processada.".

service é API key E assinatura, não uma ou outra

À primeira vista o modo service pode parecer exigir só o header X-Service-Api-Key. Não é: a rota também exige o JWS em X-Lootfy-Signature — a API key sozinha não passa. Mande sempre os dois headers nas rotas service.

service-or-bearer

Aceita ou a identidade de servidor (X-Service-Api-Key + JWS) ou um Bearer de usuário. Serve às rotas que fazem sentido tanto para o servidor quanto para uma pessoa autenticada, resolvendo a entidade certa a partir de qual credencial chegou. Como nos outros modos com Bearer, a autenticação roda antes de validar o corpo: sem credencial válida, a resposta é 401 seja qual for o payload.

signature-only

Exige só a assinatura JWS em X-Lootfy-Signature, sem nenhuma API key. É o modo das duas rotas transportadas pelo client do jogo: registrar anúncio e criar transação. Aqui o jti funciona como chave de idempotência: reusar o mesmo envelope num retry devolve o mesmo resultado, em vez de recusar.

Por que criar transação e registrar anúncio são signature-only

Estas duas rotas nascem de uma ação do jogador na tela do jogo — anunciar um item, comprar um item — e são carregadas até a Lootfy pelo client, que roda na máquina do jogador. Esse é território hostil: qualquer coisa que o client carregue, o dono da máquina pode ler. Se essas rotas exigissem a X-Service-Api-Key, a chave secreta do servidor teria de viajar pela máquina do jogador para chegar até nós — e vazaria na primeira inspeção.

A solução é o servidor assinar a oferta antes de entregá-la ao client, e o client transportar só o envelope assinado. A assinatura JWS é a única credencial: prova que o servidor autorizou aquela oferta específica, sem que nenhum segredo reutilizável passe pela mão do jogador. É por isso que o jti vira chave de idempotência aqui, e não nonce — o client pode reenviar o mesmo envelope legítimo num retry de rede, e reprocessá-lo não pode gerar um segundo anúncio ou uma segunda transação.

Frescor e integridade, não sigilo

Todo envelope assinado carrega iat/exp curtos (frescor exp − iat ≤ 300s) e um jti. A assinatura garante quem assinou e que o corpo não mudou — não esconde o conteúdo. Mantenha o relógio sincronizado por NTP: relógio torto vira 401 intermitente e difícil de diagnosticar.

Resumo por rota de integração

Rota	Modo	Header(s)
POST /v1/api/character-links (vincular personagem)	service-only	X-Service-Api-Key + X-Lootfy-Signature
POST /v1/api/market/listings (registrar anúncio)	signature-only	X-Lootfy-Signature
PUT /v1/api/market/listings (ajustar ou retirar anúncio)	service-only	X-Service-Api-Key + X-Lootfy-Signature
GET /v1/api/market/eligibility/{characterRef}	service-only	X-Service-Api-Key + X-Lootfy-Signature
POST /v1/api/transactions (criar transação)	signature-only	X-Lootfy-Signature
GET /v1/api/transactions/{transactionId} (consultar transação)	service-only	X-Service-Api-Key + X-Lootfy-Signature
POST .../delivery (confirmar entrega) · .../delivery-failure (reportar falha de entrega)	service-only	X-Service-Api-Key + X-Lootfy-Signature

Erros e status HTTP O que significa cada 401, 403, 404 e 409 do lado do parceiro.

Endpoints e status A lista completa das rotas de integração e o que já pode ser consumido.