Autenticação

Chave de API

O Guardian usa uma chave de API sp_live_* fornecida pela equipe da Surt - mas na v0.3.0 essa chave fica somente no seu backend. Ela é usada para gerar JWTs de curta duração e nunca chega ao cliente (aplicativo móvel ou web). O cliente só guarda os JWTs de curta duração que o seu backend lhe entrega.

Obtendo Sua Chave de API

1. Entre em contato com a equipe da Surt para obter suas credenciais de organização
2. Faça login no seu Painel Surt
3. Navegue até Configurações → Desenvolvedor
4. Copie sua chave de API e armazene-a como um segredo no lado do servidor

Como a autenticação funciona (v0.3.0)

1. Seu backend guarda a chave de API sp_live_* (segredo no lado do servidor).
2. Antes de chamar verify(), seu aplicativo solicita um token ao seu próprio backend.
3. Seu backend chama POST /geolocation/preflight com Authorization: Bearer <api key> e o contexto da transação, e então retorna data.token (o JWT) para o aplicativo.
4. Seu aplicativo passa o JWT para verify(jwt).

Observações:

• JWT novo a cada verify() - cada JWT é de uso único; reutilizar um JWT é rejeitado pelo backend.
• O JWT do collect() é opcional - passe-o apenas para embutir o IP público do dispositivo no payload. Como collect() não exige um JWT por chamada, seu JWT pode ser reutilizado ou totalmente omitido.

Requisição de preflight

POST https://api.surt.com/geolocation/preflight
Authorization: Bearer sp_live_xxx
Content-Type: application/json

{
  "customer_id": "user_abc123",
  "transaction_type": "login",
  "transaction_name": "User Login",
  "name": "John Doe",
  "email": "john@example.com"
}

Resposta:

{
  "data": {
    "token": "<jwt>"
  }
}

O contexto do cliente e da transação vive nas claims do JWT (definidas pelo seu backend no momento do preflight), portanto o cliente nunca passa um id de cliente ou um tipo de transação.

Tokens de Acesso a Pacotes

O próprio SDK é distribuído como um pacote privado. Você também receberá tokens de acesso para a instalação do pacote. Eles são separados da chave de API acima:

Plataforma	Tipo de Token	Onde Configurar
React Native	token npm	.npmrc na raiz do projeto
iOS	token GitHub	~/.netrc
Android	token GitHub	gradle.properties

Consulte os guias de instalação específicos de cada plataforma para mais detalhes:

• React Native
• iOS
• Android

Ambientes

Ambiente	URL Base	Uso
production	https://api.surt.com	Tráfego real
sandbox	https://sandbox-api.surt.com	Testes e desenvolvimento

aviso

Mantenha sua chave de API sp_live_* no lado do servidor o tempo todo - ela é usada apenas para gerar JWTs de curta duração. Nunca a incorpore em código de aplicativo ou de cliente web. O cliente só guarda JWTs de curta duração.