IAM - Identity and Access Management

O Building Block IAM fornece funcionalidades para gerenciamento de identidade e acesso na Catalisa Platform.

Visão Geral

O IAM é um módulo global, ou seja, não requer escopo de organização para algumas operações (como autenticação). Ele é responsável por:

• Autenticação de usuários e aplicações
• Gerenciamento de usuários
• Gerenciamento de organizações
• Controle de acesso baseado em roles (RBAC)
• Associações usuário-organização-role

Base URL

https://api.catalisa.io/iam

Recursos

Recurso	Descrição
OAuth	Autenticação e tokens de acesso
Usuários	Gerenciamento de usuários
Organizações	Gerenciamento de organizações
Roles	Roles e permissões
Associations	Associações usuário-organização

Endpoints

Públicos (sem autenticação)

Método	Endpoint	Descrição
POST	/oauth/token	Obter token de acesso
POST	/api/v1/users/login	Login de usuário

Autenticados

Método	Endpoint	Descrição
POST	/api/v1/users	Criar usuário
GET	/api/v1/users	Listar usuários
GET	/api/v1/users/:id	Obter usuário
PATCH	/api/v1/users/:id	Atualizar usuário
DELETE	/api/v1/users/:id	Excluir usuário
POST	/api/v1/organizations	Criar organização
GET	/api/v1/organizations	Listar organizações
GET	/api/v1/organizations/:id	Obter organização
PATCH	/api/v1/organizations/:id	Atualizar organização
DELETE	/api/v1/organizations/:id	Excluir organização
POST	/api/v1/organizations/:id/client-secret	Definir client secret
GET	/api/v1/roles	Listar roles
GET	/api/v1/roles/:name/permissions	Obter permissões de uma role
GET	/api/v1/permissions	Listar todas as permissões
POST	/api/v1/associations	Atribuir role a usuário
DELETE	/api/v1/associations	Remover role de usuário
GET	/api/v1/users/:id/associations	Listar associações do usuário
GET	/api/v1/organizations/:id/members	Listar membros da organização

Conceitos Importantes

Usuários

Usuários são entidades que podem se autenticar na plataforma. Cada usuário possui:

• Email único
• Senha (hash)
• Status (ativo, inativo, bloqueado, pendente)
• Flag de MFA

Organizações

Organizações representam tenants na plataforma. Tipos disponíveis:

• cliente - Organização cliente
• parceiro - Organização parceira
• dono - Organização proprietária

Roles e Permissões

O sistema utiliza RBAC para controle de acesso. Cada role possui um conjunto de permissões predefinidas.

Associações

Associações vinculam usuários a organizações com uma role específica. Um usuário pode estar associado a múltiplas organizações com diferentes roles.

Exemplo Rápido

Fluxo básico para criar uma organização e adicionar um usuário:

// 1. Obter token de acesso (Client Credentials)
const tokenResponse = await fetch('https://api.catalisa.io/iam/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: 'sua-org-id',
    client_secret: 'seu-secret',
  }),
});
const { access_token } = await tokenResponse.json();

// 2. Criar usuário
const userResponse = await fetch('https://api.catalisa.io/iam/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'novo.usuário@empresa.com',
    password: 'senhaSegura123',
  }),
});
const { data: user } = await userResponse.json();

// 3. Associar usuário a organização com role ADMIN
await fetch('https://api.catalisa.io/iam/api/v1/associations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: user.id,
    organizationId: 'org-id',
    roleId: 1, // ADMIN
  }),
});

Diagrama de Relacionamentos

┌────────────────┐         ┌─────────────────────┐         ┌────────────────┐
│     User       │         │    Association      │         │  Organization  │
├────────────────┤         ├─────────────────────┤         ├────────────────┤
│ id             │◄───────►│ userId              │◄───────►│ id             │
│ email          │         │ organizationId      │         │ name           │
│ status         │         │ roleId              │         │ slug           │
│ mfaEnabled     │         │ roleName            │         │ type           │
└────────────────┘         └─────────────────────┘         │ status         │
                                    │                      │ clientSecret   │
                                    ▼                      └────────────────┘
                           ┌────────────────┐
                           │     Role       │
                           ├────────────────┤
                           │ id             │
                           │ name           │
                           │ permissions[]  │
                           └────────────────┘