Pular para o conteúdo principal
Versão: Guardian v0.5.3

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​

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

Como a autenticação funciona​

  1. Seu backend guarda a chave de API sp_live_* (segredo no lado do servidor).
  2. Antes de chamar verify(), seu app 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) ao app.
  4. 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"
}
CampoTipoObrigatórioDescrição
customer_idstringNãoSeu identificador do usuário. Omita-o, ou envie uma string vazia, para uma transação anônima, por exemplo antes do login.
transaction_typestringSimlogin, sign_up, deposit, withdrawal ou uma string personalizada de até 64 caracteres. Veja Tipos de Transação.
transaction_namestringNãoRótulo legível por humanos
namestringNãoO nome do cliente
emailstringNãoO e-mail do cliente. Uma string vazia conta como ausente. Um endereço inválido retorna 400.
phonestringNãoO número de telefone do cliente. Uma string vazia conta como ausente. Um número que não pode ser interpretado retorna 400.
install_idstringNãoApenas 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ódigoQuando
400JSON malformado, transaction_type ausente, ou email, phone ou transaction_type inválido
401A requisição não tem o cabeçalho Authorization
403A chave de API é inválida ou está inativa, ou o Guardian não está habilitado para a sua organização
503Falha 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_id que 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 geolocationJwt que você passa para collect(), 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:

PlataformaTipo de TokenOnde Configurar
React Nativetoken npm.npmrc na raiz do projeto
iOStoken do GitHub~/.netrc
Androidtoken do GitHubgradle.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.

aviso

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.