Autenticação
Chave de API
O Guardian usa uma chave de API sp_live_* fornecida pela equipe da Surt. Apenas o seu backend guarda essa chave. Seu backend a usa para solicitar JWTs, e ela nunca é enviada ao cliente (app móvel ou web). O cliente guarda apenas os JWTs que seu backend entrega.
Obtendo Sua Chave de API
- Entre em contato com a equipe da Surt para obter as credenciais da sua organização
- Faça login no seu Surt Dashboard
- Navegue até Settings → Developer
- Copie sua chave de API e armazene-a como um segredo no lado do servidor
Como a autenticação funciona
- Seu backend guarda a chave de API
sp_live_*(segredo no lado do servidor). - Antes de chamar
verify(), seu app solicita um token ao seu próprio backend. - Seu backend chama
POST /geolocation/preflightcomAuthorization: Bearer <api key>e o contexto da transação, e então retornadata.token(o JWT) ao app. - Seu app passa o JWT para
verify(jwt).
Observações:
- Um JWT por transação. Solicite um novo JWT para cada transação. Um JWT expira 30 minutos após ser emitido.
- O JWT de
collect()é opcional. Passe-o para resolver o IP público do dispositivo para dentro do payload e para aplicar as configurações de atestação da sua organização. Veja Collect (Servidor para Servidor).
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",
"phone": "+15555550100"
}
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
customer_id | string | Não | Seu identificador do usuário. Omita-o, ou envie uma string vazia, para uma transação anônima, por exemplo antes do login. |
transaction_type | string | Sim | login, sign_up, deposit, withdrawal ou uma string personalizada de até 64 caracteres. Veja Tipos de Transação. |
transaction_name | string | Não | Rótulo legível por humanos |
name | string | Não | O nome do cliente |
email | string | Não | O e-mail do cliente. Uma string vazia conta como ausente. Um endereço inválido retorna 400. |
phone | string | Não | O número de telefone do cliente. Uma string vazia conta como ausente. Um número que não pode ser interpretado retorna 400. |
install_id | string | Não | Apenas Guardian Web. Veja Install id web. |
Resposta:
{
"data": {
"token": "<jwt>"
}
}
O contexto de cliente e transação fica nas claims do JWT (definidas pelo seu backend no preflight), então o cliente nunca passa um ID de cliente nem um tipo de transação.
data.token expira 30 minutos após ser emitido.
| Código | Quando |
|---|---|
400 | JSON malformado, transaction_type ausente, ou email, phone ou transaction_type inválido |
401 | A requisição não tem o cabeçalho Authorization |
403 | A chave de API é inválida ou está inativa, ou o Guardian não está habilitado para a sua organização |
503 | Falha temporária. Repita a requisição. |
Veja Códigos de Erro para os corpos de resposta.
Install id web (v0.5.0)
O Guardian Web v0.5.0 adiciona um install_id opcional ao preflight para que a
identidade de dispositivo de um navegador possa ser persistida em um cookie first-party e sobreviva à
remoção do armazenamento. Aplica-se apenas ao @surtai/guardian-web; os SDKs nativos o ignoram.
-
Requisição - inclua o
install_idque seu backend leu do cookie first-party (omita-o na primeira visita):{
"customer_id": "user_abc123",
"transaction_type": "login",
"install_id": "<id from your first-party cookie, or omit>"
} -
Resposta - o preflight devolve esse id (ou gera um novo) e também o embute como uma claim do JWT. O SDK web lê a claim do
geolocationJwtque você passa paracollect(), e somente quando o navegador não tem um install id armazenado. Redefina seu cookie first-party a partir dele:{
"data": {
"token": "<jwt, now carrying an install_id claim>",
"install_id": "<id to store in your first-party cookie>"
}
}
Isso é opcional - o web funciona sem ele. Veja Guardian Web → Migrando v0.4 → v0.5 para o fluxo completo e o repasse do cookie de ~5 linhas.
Tokens de Acesso a Pacotes
O SDK em si é distribuído como um pacote privado. Você também receberá tokens de acesso para a instalação do pacote. Eles são independentes da chave de API acima:
| Plataforma | Tipo de Token | Onde Configurar |
|---|---|---|
| React Native | token npm | .npmrc na raiz do projeto |
| iOS | token do GitHub | ~/.netrc |
| Android | token do GitHub | gradle.properties |
Veja os guias de instalação de cada plataforma para mais detalhes:
URL base
O SDK sempre aponta para produção em https://api.surt.com.
Mantenha sua chave de API sp_live_* sempre no lado do servidor. Ela é usada apenas para gerar JWTs. Nunca a embuta no código do app ou do cliente web. O cliente guarda apenas JWTs, que expiram após 30 minutos.