Preparando para fazer uma solicitação de API autenticada

🔐 Preparando para fazer uma solicitação de API autenticada

Depois de criar e configurar uma conta de serviço, seu aplicativo deve executar as seguintes etapas:

Crie um JSON Web Token (JWT), composto de cabeçalho, payload e assinatura.
Solicite um token de acesso da plataforma de autenticação OAuth2.
Processe a resposta JSON retornada pela plataforma.

Se a resposta contiver um válido access token, seu aplicativo pode usá-lo para chamar APIs do Altbank SDK para as quais a conta de serviço tem permissão.

Caso contrário, o JWT ou a solicitação podem ser inválidos, ou a conta de serviço pode não ter as permissões necessárias.

Os tokens de acesso são válidos para 3600 segundos por padrão. Após expirar, seu aplicativo deve gerar e assinar um novo JWT e solicitar outro token de acesso.

1. Criando o JWT

O JWT (JSON Web Token) consiste em três partes:

Header (metadata)
Payload (claims)
Signature (integrity)

Essas partes são codificadas usando Base64url e combinadas da seguinte forma:

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

The base string for the signature is constructed using:

{Header}.{Payload}

JWT Payload Example

{
  "sub": "3komo1gtbuj812ne3rlek1p7vv",
  "token_use": "access",
  "scope": "tenants/messenger-email tenants/messenger-sms",
  "auth_time": 1748105091,
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_LOKml7TLn",
  "exp": 1748108691,
  "iat": 1748105091,
  "version": 2,
  "jti": "ecf38e99-79b1-4279-8d7b-8e16ac6dc470",
  "client_id": "3komo1gtbuj812ne3rlek1p7vv"
}

Descrições de campo

Campo	Descrições
sub	O assunto — identificador exclusivo da conta de serviço.
token_use	Indica a finalidade do token — deve ser "access".
scope	Permissões solicitadas — por exemplo, acesso a determinados produtos/APIs.
auth_time	Unix timestamp of authentication.
iss	Emissor do token — geralmente a URL do provedor de identidade.
exp	Prazo de validade(Unix timestamp).
iat	Emitido no momento (Unix timestamp).
version	Versão do token — usada internamente para lógica de validação.
jti	JWT ID — um identificador exclusivo para o token (usado para evitar repetição).
client_id	O identificador do cliente para o aplicativo registrado (Altbank).