Roles e Permissões

Gerenciamento de roles e permissões no sistema RBAC da Catalisa Platform.

Endpoints

Método	Endpoint	Descrição	Permissão
GET	/api/v1/roles	Listar roles	IAM_ROLES_READ
GET	/api/v1/roles/:name/permissions	Obter permissões de uma role	IAM_ROLES_READ
GET	/api/v1/roles/permissions/all	Listar todas as permissões por role	IAM_ROLES_READ
GET	/api/v1/permissions	Listar todas as permissões	IAM_ROLES_READ

Roles Disponíveis

Role	Descrição
ADMIN	Administrador com acesso total
IAM_MANAGER	Gerencia usuários, organizacoes e associacoes
CUSTOMER_MANAGER	Gerencia clientes (pessoas e empresas)
PRODUCT_MANAGER	Gerencia produtos de crédito
DECISION_MANAGER	Gerencia motor de decisão
PRICING_MANAGER	Gerencia pricing e risk bands
FILE_MANAGER	Gerencia arquivos e documentos
DOCUMENT_OPERATOR	Opera validações de documentos
VERIFICATION_OPERATOR	Opera verificações (KYC, face recognition)
WEBHOOK_MANAGER	Gerencia webhooks
VIEWER	Apenas visualização (somente leitura)

Permissões por Módulo

IAM

Permissão	Descrição
IAM_USERS_CREATE	Criar usuários
IAM_USERS_READ	Listar e visualizar usuários
IAM_USERS_UPDATE	Atualizar usuários
IAM_USERS_DELETE	Excluir usuários
IAM_ORGANIZATIONS_CREATE	Criar organizações
IAM_ORGANIZATIONS_READ	Listar e visualizar organizacoes
IAM_ORGANIZATIONS_UPDATE	Atualizar organizações
IAM_ORGANIZATIONS_DELETE	Excluir organizações
IAM_ROLES_READ	Listar roles e permissões
IAM_ASSOCIATIONS_CREATE	Criar associações usuário-org
IAM_ASSOCIATIONS_READ	Listar associações
IAM_ASSOCIATIONS_DELETE	Remover associações

Customers

Permissão	Descrição
CUSTOMERS_PEOPLE_CREATE	Criar pessoas
CUSTOMERS_PEOPLE_READ	Listar e visualizar pessoas
CUSTOMERS_PEOPLE_UPDATE	Atualizar pessoas
CUSTOMERS_PEOPLE_DELETE	Excluir pessoas
CUSTOMERS_COMPANIES_CREATE	Criar empresas
CUSTOMERS_COMPANIES_READ	Listar e visualizar empresas
CUSTOMERS_COMPANIES_UPDATE	Atualizar empresas
CUSTOMERS_COMPANIES_DELETE	Excluir empresas

Products

Permissão	Descrição
PRODUCTS_CREATE	Criar produtos
PRODUCTS_READ	Listar e visualizar produtos
PRODUCTS_UPDATE	Atualizar produtos
PRODUCTS_DELETE	Excluir produtos

Decision Engine

Permissão	Descrição
DECISION_PROJECTS_CREATE	Criar projetos
DECISION_PROJECTS_READ	Listar e visualizar projetos
DECISION_PROJECTS_UPDATE	Atualizar projetos
DECISION_PROJECTS_DELETE	Excluir projetos
DECISION_VERSIONS_CREATE	Criar versões de decisões
DECISION_VERSIONS_READ	Listar e visualizar versoes
DECISION_VERSIONS_PUBLISH	Publicar versões
DECISION_TAGS_MANAGE	Gerenciar tags
DECISION_EXECUTE	Executar decisões
DECISION_LOGS_READ	Visualizar logs de execução

Files

Permissão	Descrição
FILES_CREATE	Criar e fazer upload de arquivos
FILES_READ	Listar e baixar arquivos
FILES_DELETE	Excluir arquivos

Pricing Engine

Permissão	Descrição
PRICING_RISK_BANDS_CREATE	Criar risk bands
PRICING_RISK_BANDS_READ	Listar e visualizar risk bands
PRICING_RISK_BANDS_UPDATE	Atualizar risk bands
PRICING_RISK_BANDS_DELETE	Excluir risk bands
PRICING_RULES_CREATE	Criar pricing rules
PRICING_RULES_READ	Listar e visualizar pricing rules
PRICING_RULES_UPDATE	Atualizar pricing rules
PRICING_RULES_DELETE	Excluir pricing rules
PRICING_CALCULATE	Executar calculos de pricing

Calculations

Permissão	Descrição
CALCULATIONS_EXECUTE	Executar calculadoras financeiras

Webhooks

Permissão	Descrição
WEBHOOKS_SUBSCRIPTIONS_CREATE	Criar subscrições
WEBHOOKS_SUBSCRIPTIONS_READ	Listar subscrições
WEBHOOKS_SUBSCRIPTIONS_UPDATE	Atualizar subscrições
WEBHOOKS_SUBSCRIPTIONS_DELETE	Excluir subscrições
WEBHOOKS_REQUESTS_CREATE	Criar requisições
WEBHOOKS_REQUESTS_READ	Listar requisições

---

Listar Roles

GET /api/v1/roles

Lista todas as roles disponíveis no sistema.

cURL

curl 'https://iam.stg.catalisa.app/api/v1/roles' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const response = await fetch('https://iam.stg.catalisa.app/api/v1/roles', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

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

Response (200 OK)

{
  "data": [
    {
      "type": "roles",
      "id": "1",
      "attributes": {
        "name": "ADMIN",
        "description": "Administrador com acesso total"
      }
    },
    {
      "type": "roles",
      "id": "2",
      "attributes": {
        "name": "CUSTOMER_MANAGER",
        "description": "Gerencia clientes"
      }
    }
  ]
}

---

Obter Permissões de uma Role

GET /api/v1/roles/:roleName/permissions

Lista as permissões associadas a uma role específica.

cURL

curl 'https://iam.stg.catalisa.app/api/v1/roles/ADMIN/permissions' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const roleName = 'ADMIN';

const response = await fetch(`https://iam.stg.catalisa.app/api/v1/roles/${roleName}/permissions`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

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

Response (200 OK)

{
  "data": {
    "role": "ADMIN",
    "permissions": [
      "IAM_USERS_CREATE",
      "IAM_USERS_READ",
      "IAM_USERS_UPDATE",
      "IAM_USERS_DELETE",
      "IAM_ORGANIZATIONS_CREATE",
      "IAM_ORGANIZATIONS_READ",
      "CUSTOMERS_PEOPLE_CREATE",
      "CUSTOMERS_PEOPLE_READ"
    ]
  }
}

---

Listar Todas as Permissões por Role

GET /api/v1/roles/permissions/all

Lista todas as roles com suas respectivas permissões.

cURL

curl 'https://iam.stg.catalisa.app/api/v1/roles/permissions/all' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const response = await fetch('https://iam.stg.catalisa.app/api/v1/roles/permissions/all', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

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

Response (200 OK)

{
  "data": [
    {
      "role": "ADMIN",
      "permissions": ["IAM_USERS_CREATE", "IAM_USERS_READ", "..."]
    },
    {
      "role": "CUSTOMER_MANAGER",
      "permissions": ["CUSTOMERS_PEOPLE_CREATE", "CUSTOMERS_PEOPLE_READ", "..."]
    }
  ]
}

---

Listar Todas as Permissões

GET /api/v1/permissions

Lista todas as permissões disponíveis no sistema.

cURL

curl 'https://iam.stg.catalisa.app/api/v1/permissions' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const response = await fetch('https://iam.stg.catalisa.app/api/v1/permissions', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

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

Response (200 OK)

{
  "data": [
    "IAM_USERS_CREATE",
    "IAM_USERS_READ",
    "IAM_USERS_UPDATE",
    "IAM_USERS_DELETE",
    "IAM_ORGANIZATIONS_CREATE",
    "CUSTOMERS_PEOPLE_CREATE",
    "PRODUCTS_CREATE",
    "DECISION_EXECUTE",
    "CALCULATIONS_EXECUTE"
  ]
}

---

Verificando Permissões no Token

O token JWT inclui as permissões do usuário no payload:

{
  "sub": "user-id",
  "organizationId": "org-id",
  "permissions": [
    "IAM_USERS_READ",
    "CUSTOMERS_PEOPLE_CREATE",
    "CUSTOMERS_PEOPLE_READ"
  ],
  "iat": 1709123456,
  "exp": 1709127056
}

Exemplo de Verificação no Frontend

function hasPermission(token, permission) {
  const payload = JSON.parse(atob(token.split('.')[1]));
  return payload.permissions?.includes(permission) ?? false;
}

// Uso
const canCreateUser = hasPermission(accessToken, 'IAM_USERS_CREATE');
if (canCreateUser) {
  // Mostrar botão de criar usuário
}

---

Erros Comuns

Código	Erro	Descrição
404	NOT_FOUND	Role não encontrada
403	FORBIDDEN	Sem permissão para visualizar roles