Autenticação

A plataforma Liqi utiliza diferentes mecanismos de autenticação dependendo da API. Esta página apresenta uma visão geral dos métodos disponíveis e quando usar cada um.

Visão geral dos métodos

Método	API	Como funciona	Quando usar
Sem autenticação	Public API	Nenhum header necessário	Consultar dados públicos de séries, patrimônios e ativos
API Key	Developer API	Header `X-API-Key` com chave estática	Acessar dados estendidos de contratos e metadados blockchain
RSA-SHA256	TIDC v1	Assinatura digital por requisição	Cessão de crédito, liquidação e operações financeiras reguladas
JWT (EdDSA)	CaaS	Bearer token obtido via `POST /v1/auth/login`	Trading, carteiras, ordens e operações em exchanges

1. Sem autenticação (Public API)

Os endpoints da Public API são abertos e não requerem nenhum tipo de credencial:

Bash

curl "https://api.liqi.com.br/public/tranches?status=ACTIVE"

Todos os endpoints sob o prefixo /public/ são acessíveis sem autenticação.

Casos de uso: Dashboards públicos, aggregators de dados, integração com sites de terceiros.

2. API Key (Developer API)

A Developer API utiliza uma chave estática enviada no header X-API-Key em cada requisição.

Obtendo sua API Key

Solicite sua chave via suporte ou no painel de desenvolvedor
Você receberá uma chave no formato lq_dev_xxxxxxxxxxxxxxxxxxxx
Armazene a chave de forma segura — ela não será exibida novamente

Usando a API Key

Bash

curl "https://api.liqi.com.br/developer/contracts" \
  -H "X-API-Key: lq_dev_xxxxxxxxxxxxxxxxxxxx"

TypeScript

const response = await fetch(
  "https://api.liqi.com.br/developer/contracts",
  {
    headers: {
      "X-API-Key": "lq_dev_xxxxxxxxxxxxxxxxxxxx",
    },
  }
);

Boas práticas

Nunca exponha sua API Key em código frontend ou repositórios públicos
Use variáveis de ambiente para armazenar a chave
Rotacione a chave periodicamente via painel de desenvolvedor
Cada chave possui escopos definidos — solicite apenas os escopos necessários

3. RSA-SHA256 (TIDC v1)

A API TIDC v1 utiliza assinatura digital RSA-SHA256 para garantir integridade e autenticidade de cada requisição. Esse método é exigido por compliance regulatório.

Como funciona

Você gera um par de chaves RSA (2048-bit mínimo)
Cadastra a chave pública na plataforma Liqi
Para cada requisição, assina o payload com sua chave privada
Envia a assinatura no header X-Signature

Gerando as chaves

Bash

# Gerar chave privada (RSA 2048-bit)
openssl genrsa -out private-key.pem 2048

# Extrair chave pública
openssl rsa -in private-key.pem -pubout -out public-key.pem

Assinando uma requisição

O payload a ser assinado é composto por:

Text

{method}\n{path}\n{timestamp}\n{body}

Onde:

method: método HTTP em uppercase (ex: POST)
path: path completo com query string (ex: /tidc/v1/credit-batches)
timestamp: timestamp Unix em segundos (validade de 5 minutos)
body: corpo da requisição em JSON (string vazia para GET)

TypeScript

import crypto from "crypto";
import fs from "fs";

const privateKey = fs.readFileSync("private-key.pem", "utf-8");
const timestamp = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify({ /* payload */ });

const signaturePayload = `POST\n/tidc/v1/credit-batches\n${timestamp}\n${body}`;

const signature = crypto
  .createSign("RSA-SHA256")
  .update(signaturePayload)
  .sign(privateKey, "base64");

const response = await fetch(
  "https://api.liqi.com.br/tidc/v1/credit-batches",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": "sua-api-key",
      "X-Timestamp": timestamp,
      "X-Signature": signature,
    },
    body,
  }
);

Headers obrigatórios

Header	Descrição
`X-API-Key`	Sua API Key TIDC v1
`X-Timestamp`	Timestamp Unix em segundos
`X-Signature`	Assinatura RSA-SHA256 em Base64
`Content-Type`	`application/json`

Para documentação completa, consulte TIDC v1 — Autenticação.

4. JWT (CaaS)

A API CaaS utiliza JSON Web Tokens com assinatura EdDSA (Ed25519). O fluxo é:

Autentique-se com apiKey + secretKey para receber um access token
Use o access token como Bearer token nas requisições subsequentes
Quando o token expirar, use o refresh token para obter um novo

Autenticação inicial

Bash

curl -X POST "https://api.liqi.com.br/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "sua-api-key",
    "secretKey": "sua-secret-key"
  }'

Resposta:

JSON

{
  "accessToken": "eyJhbGciOiJFZERTQSIs...",
  "refreshToken": "eyJhbGciOiJFZERTQSIs...",
  "expiresIn": 3600
}

Usando o token

Bash

curl "https://api.liqi.com.br/v1/wallets" \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..."

Renovando o token

Bash

curl -X PUT "https://api.liqi.com.br/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJFZERTQSIs..."
  }'

Ciclo de vida do token

Token	Validade	Uso
Access Token	1 hora	Autorização de requisições (`Authorization: Bearer`)
Refresh Token	7 dias	Renovação do access token sem re-autenticação

Para documentação completa, consulte CaaS — Autenticação.

Comparação rápida

Text

Public API    -->  Nenhum header
Developer API -->  X-API-Key: lq_dev_xxx
TIDC v1       -->  X-API-Key + X-Timestamp + X-Signature (RSA-SHA256)
CaaS          -->  Authorization: Bearer <jwt>

Segurança

Independentemente do método de autenticação, todas as comunicações com a API da Liqi devem ser feitas via HTTPS (TLS 1.2+). Requisições HTTP simples serão rejeitadas com redirect 301.

Recomendações

Armazene credenciais em cofres de segredos (AWS Secrets Manager, HashiCorp Vault, etc.)
Nunca logue payloads de autenticação em texto plano
Implemente rotação periódica de chaves e tokens
Monitore o uso de suas credenciais via logs de auditoria

Próximos passos

Rate Limits — Limites de requisição por API
TIDC v1 — Autenticação — Guia completo de assinatura RSA
CaaS — Autenticação — Fluxo JWT detalhado