Stater Platform

Autenticação (API Key)

POST /authenticate/clients — autentica qualquer titular do tenant sem senha, usando a Tenant API Key.

Autenticação (API Key)

Troca a Tenant API Key do seu white label pelo JWT de um titular do seu tenant, informando apenas o CPF/CNPJ — sem a senha do cliente final. Uso exclusivamente server-to-server. Mesmo shape de resposta do POST /authenticate.

POST/authenticate/clients

Uso exclusivamente server-to-server — nunca exponha a Tenant API Key em app mobile, front-end ou repositório. O token vale 24h e é restrito ao titular informado: para operar vários titulares, repita a chamada com o documento de cada um (um token por titular, cacheável até expirar) e trate 401 re-autenticando. Revogar a chave invalida imediatamente todos os tokens emitidos com ela, mesmo dentro das 24h. Operações de escrita (Pix, TEV) continuam exigindo o pin do cliente final, salvo se a Isenção de PIN via API de Tenant estiver habilitada para o seu tenant. Erros: 400 quando o X-Tenant-Id está ausente/inválido ou o document está fora de 11–14 dígitos; 401 quando a chave está ausente, inválida, revogada, expirada ou é de outro tenant, quando o documento não corresponde a um titular do seu tenant, e quando o titular está bloqueado (Conta bloqueada. Procure o suporte.); 429 no rate limit. Veja o guia de Autenticação para ciclo de vida e rotação da chave.

Headers

  • AcceptObrigatório
    string
    application/json
  • Content-TypeObrigatório
    string
    application/json
  • X-Tenant-IdObrigatório
    string (UUID)
    Identificador do tenant (cliente WL) dono da chave e do titular.
  • X-Tenant-Api-KeyObrigatório
    string
    Tenant API Key do seu tenant, no formato tnk_<prefixo>.<segredo>.

Body

  • documentObrigatório
    string
    CPF (11 dígitos) ou CNPJ (14 dígitos) do titular, apenas números. Único campo do corpo — não há senha, PIN nem accountId.

Exemplo de requisição

curl -X POST https://baas.staterpay.io/authenticate/clients \  -H "Accept: application/json" \  -H "Content-Type: application/json" \  -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000000" \  -H "X-Tenant-Api-Key: tnk_0356d4a1.vsqBAy5sAI63nyUoxgN-NWVfmIFdX9W6" \  -d '{    "document": "12345678900"  }'

Resposta

  • token
    string (JWT)
    JWT a usar nas chamadas subsequentes no header Authorization: Bearer <token>. TTL de 24h (iat e exp do payload).
  • entityType
    "PERSON" | "COMPANY"
    Tipo da entidade autenticada — PERSON (PF) ou COMPANY (PJ).
  • entity.id
    string (UUID)
    ID interno da entidade.
  • entity.email
    string
    Email cadastrado.
  • entity.emailConfirmation
    boolean
    Se o email foi confirmado.
  • entity.phone
    string | null
    Telefone no formato E.164 (+55...).
  • entity.phoneConfirmation
    boolean
    Se o telefone foi confirmado.
  • entity.name
    string
    Nome completo (PF) ou razão social (PJ).
  • entity.document
    string
    CPF ou CNPJ, apenas dígitos.
  • entity.status
    "ACTIVE" | "BLOCKED" | "CLOSED"
    Estado atual da conta.
  • entity.onboardingStep
    string
    Etapa do onboarding. "DONE" quando concluído.
  • entity.onboardingLink
    string | null
    URL para retomar o onboarding, quando incompleto.
  • entity.onboardingRequisitionId
    number | null
    ID da requisição de onboarding (auditoria).
  • entity.hasPin
    boolean
    Se o titular tem PIN definido para operações sensíveis.
  • accounts
    array
    Contas associadas à entidade.
  • accounts[].id
    string (UUID)
    ID da conta.
  • accounts[].bank
    string
    Código do banco (3 dígitos).
  • accounts[].agency
    string
    Agência (4 dígitos).
  • accounts[].number
    string
    Número da conta.
  • accounts[].balance
    number
    Saldo atual em reais (não centavos).
  • accounts[].status
    "APPROVED" | "PENDING" | "REJECTED"
    Estado de provisionamento da conta.
  • accounts[].monthlyGoal
    number
    Meta de gastos mensal definida pelo usuário.
  • accounts[].monthlySpending
    number
    Gastos no mês corrente.
  • accounts[].savingsProgress
    number
    Progresso na meta de economia.
json
// PF — entityType: "PERSON"{  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<payload>.<signature>",  "entityType": "PERSON",  "entity": {    "id": "00000000-0000-0000-0000-000000000001",    "email": "fulano@example.com",    "emailConfirmation": false,    "phone": null,    "phoneConfirmation": false,    "name": "Fulano de Tal",    "document": "12345678900",    "status": "ACTIVE",    "onboardingStep": "DONE",    "onboardingLink": null,    "onboardingRequisitionId": null,    "hasPin": true  },  "accounts": [    {      "id": "00000000-0000-0000-0000-000000000010",      "bank": "000",      "agency": "0001",      "number": "1000001",      "balance": 6.44,      "status": "APPROVED",      "monthlyGoal": 0,      "monthlySpending": 3.10,      "savingsProgress": 0    }  ]}// PJ — entityType: "COMPANY"{  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<payload>.<signature>",  "entityType": "COMPANY",  "entity": {    "id": "00000000-0000-0000-0000-000000000002",    "email": "contato@empresa.com.br",    "emailConfirmation": true,    "phone": "+5511900000000",    "phoneConfirmation": true,    "name": "NOME EMPRESA LTDA",    "document": "12345678000190",    "status": "ACTIVE",    "onboardingStep": "DONE",    "onboardingLink": null,    "onboardingRequisitionId": null,    "hasPin": true  },  "accounts": [    {      "id": "00000000-0000-0000-0000-000000000020",      "bank": "000",      "agency": "0001",      "number": "1000002",      "balance": 224.93,      "status": "APPROVED",      "monthlyGoal": 0,      "monthlySpending": 22.20,      "savingsProgress": 0    }  ]}
URL base:https://baas.staterpay.io

Autenticação

POST /authenticate — autentica PF/PJ no contexto de um tenant e retorna JWT.

Consultar conta

GET /accounts/:id — retorna saldo e dados da conta autenticada.

On this page

HeadersBodyExemplo de requisiçãoResposta