Autenticação

A Catalisa Platform utiliza OAuth 2.0 para autenticação. Todas as requisições aos Building Blocks (exceto endpoints públicos) requerem um token de acesso válido.

Métodos de Autenticação

1. Client Credentials (M2M)

Use este método para integração servidor-a-servidor (machine-to-machine). Ideal para backends e automações.

cURL

curl -X POST 'https://iam.stg.catalisa.app/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "sua-organização-id",
    "client_secret": "seu-client-secret"
  }'

JavaScript

async function getAccessToken(clientId, clientSecret) {
  const response = await fetch('https://iam.stg.catalisa.app/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: clientId,
      client_secret: clientSecret,
    }),
  });

  if (!response.ok) {
    throw new Error(`Erro de autenticação: ${response.status}`);
  }

  return response.json();
}

// Uso
const { access_token, expires_in } = await getAccessToken(
  'sua-organização-id',
  'seu-client-secret'
);

Resposta

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

2. Refresh Token

Use este método para renovar tokens expirados sem precisar das credenciais originais.

cURL

curl -X POST 'https://iam.stg.catalisa.app/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "seu-refresh-token"
  }'

JavaScript

async function refreshAccessToken(refreshToken) {
  const response = await fetch('https://iam.stg.catalisa.app/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
    }),
  });

  if (!response.ok) {
    throw new Error(`Erro ao renovar token: ${response.status}`);
  }

  return response.json();
}

3. Login de Usuário

Use este método para autenticar usuários finais em aplicações frontend.

cURL

curl -X POST 'https://iam.stg.catalisa.app/api/v1/users/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "usuário@exemplo.com",
    "password": "senha123"
  }'

JavaScript

async function loginUser(email, password) {
  const response = await fetch('https://iam.stg.catalisa.app/api/v1/users/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email, password }),
  });

  if (!response.ok) {
    throw new Error('Credenciais inválidas');
  }

  return response.json();
}

Usando o Token

Inclua o token em todas as requisições usando o header Authorization:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens e Expiração

Tipo	Duração	Uso
Access Token	1 hora	Requisições de API
Refresh Token	7 dias	Renovar access token

Atenção

• Tokens de acesso expiram após 1 hora
• Sempre implemente lógica de renovação automática
• Nunca exponha o client_secret no frontend

Permissões

O sistema utiliza RBAC (Role-Based Access Control). Cada token carrega as permissões do usuário/organização.

Roles Disponíveis

Role	Descrição
ADMIN	Acesso total ao sistema
IAM_MANAGER	Gerencia usuários, organizações e API keys
CUSTOMER_MANAGER	Gerencia clientes (pessoas e empresas)
PRODUCT_MANAGER	Gerencia produtos
DECISION_MANAGER	Gerencia regras de decisão
BILLING_MANAGER	Gerencia contas, planos, assinaturas e faturamento
DOCUMENT_OPERATOR	Gerencia assinaturas eletrônicas e documentos
VERIFICATION_OPERATOR	Gerencia validação facial e documental
WEBHOOK_MANAGER	Gerencia webhooks, subscriptions e chaves de assinatura
FILE_MANAGER	Gerencia arquivos
VIEWER	Somente leitura

Permissões Principais

Permissão	Descrição
IAM_USERS_*	Operações em usuários
IAM_ORGANIZATIONS_*	Operações em organizações
IAM_ROLES_READ	Listar roles disponíveis
IAM_ASSOCIATIONS_*	Operações em associações usuário-organização
API_KEYS_*	Operações em chaves de API
CUSTOMERS_PEOPLE_*	Operações em pessoas
CUSTOMERS_COMPANIES_*	Operações em empresas
PRODUCTS_*	Operações em produtos
DECISION_*	Operações no motor de decisão
PRICING_*	Operações no pricing engine
FILES_*	Operações em arquivos
FEATURE_FLAGS_*	Operações em feature flags
SEGMENTS_*	Operações em segmentos
WEBHOOKS_SUBSCRIPTIONS_*	Operações em webhook subscriptions
WEBHOOKS_DELIVERIES_*	Operações em delivery logs
WEBHOOKS_KEYS_*	Operações em chaves de assinatura
BILLING_*	Operações no módulo de billing
ESIGNATURE_*	Operações em assinatura eletrônica
AUDIT_LOGS_READ	Consultar logs de auditoria

informação

Para a lista completa de permissões, consulte a documentação de Roles.

Módulos Globais vs Tenant-Scoped

Módulo Global (IAM)

O módulo IAM não requer escopo de organização. Endpoints como /oauth/token e /users/login são públicos.

Módulos Tenant-Scoped

Os demais módulos requerem um token com organizationId. Ao usar Client Credentials, o organizationId é automaticamente incluído no token.

Customers, Products, File Storage, Decision Engine, Decision Platform,
Calculations Engine, Pricing Engine, Feature Flags, Webhooks Engine,
API Keys, E-Signature, Billing, Audit Trail, BaaS, Data Extraction, Open Finance

Exemplo Completo

class CatalisaClient {
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.accessToken = null;
    this.tokenExpiry = null;
  }

  async getToken() {
    // Verifica se o token ainda é válido
    if (this.accessToken && this.tokenExpiry > Date.now()) {
      return this.accessToken;
    }

    // Obtém novo token
    const response = await fetch('https://iam.stg.catalisa.app/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        grant_type: 'client_credentials',
        client_id: this.clientId,
        client_secret: this.clientSecret,
      }),
    });

    const data = await response.json();
    this.accessToken = data.access_token;
    this.tokenExpiry = Date.now() + (data.expires_in * 1000) - 60000; // 1 min buffer

    return this.accessToken;
  }

  async request(method, url, body = null) {
    const token = await this.getToken();

    const options = {
      method,
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
    };

    if (body) {
      options.body = JSON.stringify(body);
    }

    const response = await fetch(url, options);
    return response.json();
  }
}

// Uso
const client = new CatalisaClient('org-id', 'secret');
const products = await client.request('GET', 'https://products.stg.catalisa.app/api/v1/products');