Guides
Start typing to search…
  1. Documentation

Guia de Autenticação

Aprenda como autenticar na API da Qesh utilizando JWT, gerenciar tokens e validar assinaturas com a chave pública.

A autenticação é o primeiro passo para consumir qualquer recurso da API Qesh. Utilizamos o padrão OAuth 2.0 Client Credentials com tokens JWT (JSON Web Token) para garantir segurança e controle de acesso.

Visão Geral do Fluxo

O diagrama abaixo ilustra o fluxo completo de autenticação:

Fluxo de autenticação
  1. Seu sistema envia as credenciais (client_id e client_secret) ao serviço IAM.
  2. O IAM valida as credenciais e retorna um token JWT.
  3. Seu sistema utiliza o token no cabeçalho Authorization: Bearer <token> para acessar os endpoints da API.

Passo 1 — Obter suas Credenciais

Antes de tudo, você precisa das suas credenciais de acesso:

CampoDescrição
client_idIdentificador único da sua aplicação
client_secretChave secreta para autenticação da sua aplicação
📘

Onde encontrar suas credenciais?

Suas credenciais são fornecidas pela equipe da Qesh no momento do onboarding. Caso não possua, entre em contato com o suporte.

Passo 2 — Gerar o Token de Autorização

Faça uma requisição POST para o endpoint de login com suas credenciais:

POST /v1/iam/users/login HTTP/1.1
Host: iam.qesh.ai
Content-Type: application/x-www-form-urlencoded

client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET&grant_type=client_credentials

Exemplo com cURL

curl -X POST https://iam.qesh.ai/v1/iam/users/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Exemplo com Node.js

const response = await fetch('https://iam.qesh.ai/v1/iam/users/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: 'SEU_CLIENT_ID',
    client_secret: 'SEU_CLIENT_SECRET',
    grant_type: 'client_credentials',
  }),
});

const { data } = await response.json();
console.log(data.access_token);

Exemplo com Python

import requests

response = requests.post(
    "https://iam.qesh.ai/v1/iam/users/login",
    data={
        "client_id": "SEU_CLIENT_ID",
        "client_secret": "SEU_CLIENT_SECRET",
        "grant_type": "client_credentials",
    },
)

token = response.json()["data"]["access_token"]
print(token)

Resposta esperada

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 300,
    "token_type": "Bearer"
  },
  "meta": {
    "request_id": "abc123",
    "timestamp": "2026-01-01T12:00:00Z"
  }
}
⚠️

O campo expires_in indica o tempo de vida do token em segundos. O valor padrão é 300 segundos (5 minutos).

Passo 3 — Utilizar o Token nas Requisições

Inclua o token retornado no cabeçalho Authorization de todas as chamadas à API:

GET /v1/connect/balance HTTP/1.1
Host: api.qesh.ai
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
🚧

Atenção ao formato

O cabeçalho deve seguir exatamente o padrão Bearer <token> (com espaço após "Bearer"). Erros de digitação ou ausência do espaço causarão falha na autenticação.

Passo 4 — Renovar o Token Expirado

Tokens JWT possuem tempo de expiração curto por segurança. Quando o token expirar, a API retornará:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Token expired"
  }
}

Estratégia recomendada: Implemente um mecanismo de renovação automática no seu sistema:

class QeshAuth {
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.token = null;
    this.expiresAt = 0;
  }

  async getToken() {
    const now = Date.now();
    // Renova 30 segundos antes de expirar para evitar requisições com token expirado
    if (this.token && this.expiresAt - 30000 > now) {
      return this.token;
    }

    const response = await fetch('https://iam.qesh.ai/v1/iam/users/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        client_id: this.clientId,
        client_secret: this.clientSecret,
        grant_type: 'client_credentials',
      }),
    });

    const { data } = await response.json();
    this.token = data.access_token;
    this.expiresAt = now + data.expires_in * 1000;
    return this.token;
  }
}

Consultar a Chave Pública

A Qesh disponibiliza uma chave pública EDCSA que pode ser utilizada para verificar a autenticidade de tokens e assinaturas emitidos pela plataforma.

GET /v1/iam/public-key HTTP/1.1
Host: iam.qesh.ai

A chave pública é especialmente útil para:

  • Validar tokens JWT localmente sem precisar chamar a API a cada requisição;
  • Verificar assinaturas de webhooks e payloads recebidos da Qesh.

Boas Práticas de Segurança

PráticaDescrição
Nunca exponha suas credenciaisArmazene client_id e client_secret em variáveis de ambiente, nunca no código-fonte.
Renove tokens proativamenteImplemente renovação automática antes da expiração (margem de ~30s).
Use HTTPS exclusivamenteTodas as chamadas devem usar HTTPS para proteger credenciais e tokens em trânsito.
Armazene o request_idGuarde o request_id das respostas para facilitar o suporte em caso de problemas.
Não compartilhe tokensCada sistema/serviço deve ter suas próprias credenciais e gerar seus próprios tokens.

Erros Comuns

StatusCódigoCausaSolução
401UNAUTHORIZEDToken ausente, inválido ou expiradoGere um novo token com suas credenciais
403FORBIDDENToken válido, mas sem permissãoVerifique as permissões da sua conta
400BAD_REQUESTCredenciais ausentes ou grant_type erradoConfira os campos client_id, client_secret e grant_type

Próximos Passos

Com seu token em mãos, você está pronto para:

Updated 20 days ago

What’s Next