IAM

O IAM responde três perguntas para todos os outros building blocks: quem é este usuário, de qual empresa ele é e o que ele tem permissão de fazer. Ele emite o token que carrega essas três respostas, e todo o resto da plataforma confia nesse token em vez de manter cadastro próprio.

Na prática isso significa que quando uma financeira contrata o Commerce e o Payments, ela não cadastra usuário duas vezes nem descobre, três meses depois, que o time de atendimento consegue estornar pagamento porque alguém esqueceu de checar permissão em um endpoint. A permissão PAYMENTS_REFUND_CREATE é a mesma string em todo lugar, e quem não a tem no token recebe 403 antes de a requisição chegar na regra de negócio.

Está em produção desde fevereiro de 2026 e é dependência obrigatória de todos os outros 31 building blocks — nenhum sobe sem ele.

O cenário. Uma plataforma B2B vende para empresas, não para pessoas. Cada empresa cliente tem seus próprios usuários, seus próprios dados, e não pode enxergar um byte da empresa vizinha. Conforme a plataforma cresce, ela deixa de ser um serviço e vira dez — e cada um precisa saber quem está chamando.

É aqui que a arquitetura se degrada em silêncio. Cada serviço novo chega com a própria noção de quem-pode-o-quê, e a plataforma passa a ter tantas implementações de autorização quantos serviços tiver.

flowchart TD
  U["Usuário da empresa cliente"] --> A["Serviço A"]
  U --> B["Serviço B"]
  U --> C["Serviço C"]
  A --> AA["Tabela de usuários própria<br/>Checagem de permissão própria"]
  B --> BB["Outra tabela<br/>Outra checagem"]
  C --> CC["Sem checagem<br/>alguém esqueceu"]
  AA --> R["Risco: regra divergente por serviço"]
  BB --> R
  CC --> R

O que trava hoje.

• Cada serviço reimplementa autorização. O time do serviço A checa permissão de um jeito, o do serviço B de outro, e o terceiro esquece de checar. O bug não aparece em teste, aparece em auditoria.
• O provedor de identidade externo não conhece o seu domínio. Auth0 sabe que o usuário fez login; não sabe se ele pode cancelar uma assinatura. A regra volta para o seu código, replicada em cada serviço.
• Multi-tenancy vira convenção, não garantia. "Todo mundo lembra de filtrar por organization_id" é uma frase que funciona até o dia em que alguém não lembra. Vazamento entre clientes é o incidente que não tem pedido de desculpas suficiente.
• Integração máquina a máquina é gambiarra. Sem M2M de verdade, o parceiro acaba com um usuário de serviço com senha em variável de ambiente e permissão de administrador.
• O custo por usuário não fecha no B2B. Preço por usuário ativo mensal foi desenhado para aplicativo de consumidor. Numa plataforma B2B com dezenas de milhares de usuários corporativos de baixa frequência, a conta cresce sem relação com o valor entregue.

O custo de não resolver. Autorização espalhada é a origem mais comum de falha de controle de acesso — a categoria "Broken Access Control" lidera o OWASP Top 10 desde 2021 (OWASP Top 10:2021). E o custo não é só o incidente: é cada novo serviço nascendo com mais duas semanas de trabalho só para reimplementar quem-pode-o-quê.

O desenho que sustenta essa tabela é simples: um único ponto emite a credencial, e todo o resto apenas verifica.

flowchart LR
  U["Usuário"] -->|"login"| IAM["IAM"]
  P["Parceiro"] -->|"client_credentials"| IAM
  IAM -->|"JWT: sub, organizationId, permissions"| BBs["32 building blocks"]
  BBs -->|"requirePermission + requireOrganization"| OK["Resposta ou 403"]

Autorização escrita uma vez

As permissões são um enum compartilhado por todos os building blocks. O middleware requirePermission é o mesmo código em todo lugar — não há trinta implementações para auditar, há uma.

O tenant vem do token, nunca do corpo da requisição

O organizationId é claim assinado. Um cliente não consegue pedir dados de outro trocando um campo no JSON, porque o campo não é lido do JSON.

Máquina a máquina de verdade

O parceiro recebe client_id (que é o identificador da própria organização) e client_secret rotacionável, troca por token de vida curta e opera com escopo reduzido ao que precisa.

Custo desacoplado do número de usuários

O IAM vem com a plataforma. Uma empresa cliente com 40 usuários corporativos não custa 40 vezes uma com um usuário.

Panorama. O mercado de identidade se dividiu em três campos. Os provedores hospedados (Auth0, Clerk, Cognito) resolvem autenticação muito bem e cobram por usuário ativo. As soluções auto-hospedadas (Keycloak, FusionAuth) entregam protocolo completo e transferem a operação para você. E, na prática, quase toda plataforma B2B acaba escrevendo uma terceira camada em cima — a autorização de domínio, que nenhum dos dois grupos resolve, porque nenhum deles sabe o que é uma fatura na sua regra de negócio.

O IAM da Catalisa nasce nesse terceiro campo. Ele não tenta ser o melhor autenticador do mercado; ele é o autorizador que já conhece os 32 building blocks.

Nossos diferenciais

1. A permissão é do domínio, não genérica. BILLING_INVOICES_VOID significa alguma coisa concreta porque o Billing a declara e o middleware a exige. Um IdP externo só conseguiria chegar aqui se você reimplementasse o catálogo inteiro dentro dele — e mantivesse os dois em sincronia para sempre.
2. O tenant não é opcional em nenhum ponto do caminho. O organizationId é claim assinado, e os building blocks tenant-scoped rejeitam token sem ele. Não é convenção de time, é o código recusando.
3. A credencial M2M já nasce com o tenant amarrado. O client_id é o identificador da organização. Não existe estado em que uma credencial de integração esteja apontando para o tenant errado, porque ela é o tenant.
4. Custo desacoplado de usuário ativo. No B2B, o número de usuários corporativos tem pouca relação com o valor entregue. Cobrar por ele penaliza exatamente o cliente que mais cresce.

Quando escolher o concorrente. O IAM ganha quando o problema é autorização de domínio em plataforma B2B multi-tenant — não quando o problema é autenticação de consumidor final. Nos três cenários abaixo, a escolha certa é outra.

flowchart TD
  Q1{"Seu produto é B2C,<br/>com login social e<br/>tela de login pronta?"}
  Q1 -->|sim| A["Auth0 ou Clerk"]
  Q1 -->|não| Q2{"Exige SAML corporativo<br/>ou LDAP?"}
  Q2 -->|sim| K["Keycloak"]
  Q2 -->|não| Q3{"Já vive na AWS, com<br/>volume alto de usuários?"}
  Q3 -->|sim| C["Amazon Cognito"]
  Q3 -->|não| I["Catalisa IAM"]

Unidade de cobrança. O IAM não é cobrado à parte. Ele é infraestrutura obrigatória de todos os outros building blocks, e cobrar por ele seria cobrar duas vezes pela mesma coisa.

O que dispara custo. Número de organizações ativas e volume de emissão de token — ambos com impacto marginal, já que a emissão é uma assinatura HS256 e a verificação não toca o banco.

Comparação de custo — cenário: plataforma B2B com 80 empresas clientes e 4.000 usuários corporativos, dos quais cerca de 2.500 acessam em um mês típico.

Ordens de grandeza para orientar conversa, não proposta comercial. Preços de Auth0 e Cognito variam por região, plano e negociação — consulte as tabelas públicas dos fornecedores na data da sua análise. O custo de engenharia é estimativa interna.

ROI

O retorno não está na linha de licença — o Cognito é mais barato que qualquer coisa. Está na engenharia que não é gasta.

flowchart LR
  A["Building block novo entra no catálogo"] --> B{"Existe IAM?"}
  B -->|não| C["2 a 4 semanas reimplementando<br/>quem-pode-o-quê + risco de errar"]
  B -->|sim| D["Declara as permissões<br/>e já nasce protegido"]
  C --> E["Coleção de serviços<br/>que não conversam"]
  D --> F["Catálogo integrado"]

Cada building block novo que entra no catálogo já nasce autorizado; sem o IAM, cada um custaria de duas a quatro semanas de trabalho só para reimplementar quem-pode-o-quê, com a chance de errar que isso carrega. Com 32 building blocks, essa é a diferença entre um catálogo e uma coleção de serviços que não conversam.

As camadas e o caminho da requisição

flowchart TD
  HTTP["HTTP"] --> HONO

  subgraph HONO["Hono app — basePath('/iam')"]
    R1["/api/v1/users<br/>usersRouter · userAssociationsRouter"]
    R2["/api/v1/organizations<br/>organizationsRouter · membersRouter"]
    R3["/api/v1/roles<br/>rolesRouter"]
    R4["/api/v1/permissions<br/>permissionsRouter"]
    R5["/api/v1/associations<br/>associationsRouter"]
    R6["/oauth<br/>oauthRouter — token · revoke"]
    R7["/health<br/>sonda com banco, cripto e JWT"]
  end

  HONO -->|"Zod parse → ResultAsync&lt;T, AppError&gt;"| SVC

  subgraph SVC["services/"]
    S1["AuthService — login, emissão de par de tokens"]
    S2["UserService — ciclo de vida do usuário"]
    S3["OrganizationService — organizações e client_secret"]
    S4["AssociationService — usuário ↔ organização ↔ papel"]
    S5["RoleService — catálogo de papéis e permissões"]
    S6["OrganizationPermissionService — o que a org contratou"]
    S7["RefreshTokenService — rotação e revogação"]
  end

  SVC --> REPO["repositories/ (Prisma)"]
  REPO --> PG[("PostgreSQL — schema iam")]

O token sai daqui e é verificado em todo lugar

O token emitido pelo IAM é consumido por todos os outros building blocks, e a verificação é o mesmo código nos 32:

flowchart LR
  C["Cliente"] -->|"Bearer JWT"| MW
  subgraph MW["Middlewares — idênticos nos 32 BBs"]
    direction TB
    A["authMiddleware<br/>verifica assinatura HS256"] --> B["requirePermission(P)<br/>P ∈ token.permissions?"]
    B --> D["requireOrganization<br/>token.organizationId presente?"]
  end
  MW --> H["Handler da regra de negócio"]

Decisões não óbvias.

• HS256 com segredo compartilhado, e não RS256. Todos os building blocks são nossos e rodam na nossa infraestrutura, então a chave pública não traria benefício e a rotação de par de chaves traria custo operacional. O trade-off aceito é que qualquer serviço com o segredo pode emitir token, não só verificar — o que é aceitável enquanto todos os consumidores forem internos. No dia em que um terceiro precisar verificar token sem poder emitir, isso vira RS256.
• JWT_SECRET com mínimo de 44 caracteres, validado no construtor. É o comprimento de uma chave de 256 bits em base64. O serviço não sobe com segredo fraco; falhar no boot é melhor que rodar inseguro.
• Preflight de JWT no startup. O JwtService.preflight() assina e verifica um token descartável antes de o serviço aceitar tráfego. Um segredo malformado quebra no boot, não na primeira requisição de um cliente.
• Permissões dentro do token, não consultadas por requisição. A verificação não toca o banco, o que mantém a latência do middleware perto de zero. O trade-off é que revogar permissão só surte efeito na renovação do token — por isso o access token dura uma hora por padrão.
• isRoot como claim explícito. Operador de plataforma precisa de acesso cross-organização. Isso é um claim booleano e nomeado, em vez de um caso especial escondido em cada rota, justamente para que seja auditável.
• Rate limit nas rotas de autenticação. POST /users/login e POST /oauth/token passam por authRateLimitMiddleware, e falhas geram evento em logSecurityEvent. Força bruta é ruidosa e limitada por padrão.

Monolito vs. standalone

Em monolito, os outros building blocks resolvem o IAM pelo container TypeDI, com chamada direta. Em standalone — o modo usado em produção — o IAM roda na porta 3001 e os demais o alcançam por HTTP via ModuleClient.

A verificação não precisa de rede em nenhum dos dois modos: qualquer serviço com o JWT_SECRET valida a assinatura localmente.

Glossário

Modelo de dados — schema iam no PostgreSQL.

Enumerações

Relacionamentos

erDiagram
  User ||--o{ Association : "pertence a"
  Organization ||--o{ Association : "tem membros"
  Role ||--o{ Association : "papel do vínculo"
  Organization ||--o{ OrganizationPermission : "contratou"
  User ||--o{ RefreshToken : "possui"

Ciclo de vida do usuário

stateDiagram-v2
  [*] --> pendente: criação (POST /users)
  pendente --> ativo: ativação (PATCH status)
  ativo --> bloqueado: suspensão (PATCH status)
  ativo --> inativo: desativação (PATCH status)
  ativo --> [*]: exclusão lógica (deletedAt)
  inativo --> [*]: exclusão lógica (deletedAt)
  bloqueado --> [*]: exclusão lógica (deletedAt)

Ciclo de vida da organização

stateDiagram-v2
  [*] --> ativo: criação (POST /organizations, padrão ativo)
  ativo --> suspenso: suspensão (PATCH status)
  suspenso --> ativo: reativação (PATCH status)
  ativo --> inativo: desativação (PATCH status)
  inativo --> ativo: reativação (PATCH status)
  ativo --> [*]: exclusão lógica (deletedAt)
  inativo --> [*]: exclusão lógica (deletedAt)
  suspenso --> [*]: exclusão lógica (deletedAt)

Como uma permissão chega ao token

flowchart TD
  A["Permissões da organização<br/>(OrganizationPermission)"] --> X{"interseção"}
  B["Permissões do papel<br/>(Role → ROLE_PERMISSIONS)"] --> X
  X --> T["token.permissions[]<br/>o que o usuário de fato pode fazer"]

Prefixo: /iam. Em standalone, a base é https://iam.stg.catalisa.app.

Usuários — /iam/api/v1/users

Organizações — /iam/api/v1/organizations

Papéis e permissões

Associações — /iam/api/v1/associations

OAuth 2.0 — /iam/oauth

Saúde

Endpoints principais em detalhe

Os dois endpoints abaixo são os que um integrador usa primeiro. O caminho é o mesmo nos dois: credencial entra, token sai.

sequenceDiagram
  participant Cli as Cliente
  participant RL as authRateLimitMiddleware
  participant Auth as AuthService
  participant DB as PostgreSQL
  participant Log as logSecurityEvent
  Cli->>RL: POST /users/login ou /oauth/token
  RL-->>Cli: 429 se o limite estourou
  RL->>Auth: credenciais
  Auth->>DB: busca usuário ou organização
  DB-->>Auth: registro + hash
  Auth->>Auth: verifica hash e resolve permissões
  Auth->>Log: LOGIN_SUCCESS / LOGIN_FAILURE / OAUTH_TOKEN_FAILURE
  Auth-->>Cli: 200 com token, ou 401

POST /iam/api/v1/users/login

Autentica por e-mail e senha. Rota pública, protegida por rate limit; sucesso e falha vão para o log de segurança.

Request

{
  "email": "admin@catalisa.app",
  "password": "senha-do-usuario",
  "organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1"
}

{
  "email": "admin@catalisa.app",
  "password": "senha-do-usuario",
  "organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1"
}

Resposta 200

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "b1000000-0000-0000-0000-000000000001",
    "email": "admin@catalisa.app",
    "status": "ativo"
  }
}

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "b1000000-0000-0000-0000-000000000001",
    "email": "admin@catalisa.app",
    "status": "ativo"
  }
}

Claims do access token

Erros

POST /iam/oauth/token

Endpoint OAuth 2.0. Suporta client_credentials (M2M) e refresh_token.

Request — client_credentials

{
  "grant_type": "client_credentials",
  "client_id": "2194956a-2d0a-4203-89a3-933319d80fa1",
  "client_secret": "cs_live_...",
  "scope": "CUSTOMERS_READ CUSTOMERS_CREATE"
}

{
  "grant_type": "client_credentials",
  "client_id": "2194956a-2d0a-4203-89a3-933319d80fa1",
  "client_secret": "cs_live_...",
  "scope": "CUSTOMERS_READ CUSTOMERS_CREATE"
}

O scope só reduz: pedir uma permissão que a organização não contratou não a concede. O filtro está em filterScopedPermissions.

Resposta 200

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

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

Erros — formato OAuth 2.0, não o envelope padrão da plataforma.

O serviço não distingue organização inexistente de segredo errado — ambos retornam invalid_client. É proposital: distinguir permitiria enumerar organizações.

POST /iam/api/v1/organizations/:organizationId/client-secret

Gera ou rotaciona o segredo M2M. O valor é retornado uma única vez; o banco guarda apenas o hash.

Resposta 200

{
  "clientId": "2194956a-2d0a-4203-89a3-933319d80fa1",
  "clientSecret": "cs_live_8f3a...",
  "warning": "Guarde este segredo agora. Ele não será exibido novamente."
}

{
  "clientId": "2194956a-2d0a-4203-89a3-933319d80fa1",
  "clientSecret": "cs_live_8f3a...",
  "warning": "Guarde este segredo agora. Ele não será exibido novamente."
}

Rotacionar invalida o segredo anterior de imediato — coordene com o parceiro antes de chamar.

Do zero a uma chamada autenticada em um building block tenant-scoped, em quatro passos.

sequenceDiagram
  autonumber
  participant Você
  participant IAM
  participant Cust as Customers
  Você->>IAM: POST /users/login (e-mail, senha, organizationId)
  IAM-->>Você: accessToken + refreshToken
  Você->>Você: decodifica o payload e confere organizationId
  Você->>Cust: GET /persons com Bearer
  Cust-->>Você: só os clientes da sua organização
  Você->>Cust: GET /persons com token inválido
  Cust-->>Você: 401

1. Autenticar

TOKEN=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "password123",
    "organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1"
  }' | jq -r .accessToken)

echo "${TOKEN:0:32}..."

TOKEN=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "password123",
    "organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1"
  }' | jq -r .accessToken)

echo "${TOKEN:0:32}..."

Resposta esperada — o começo de um JWT, prova de que a variável foi preenchida:

eyJhbGciOiJIUzI1NiIsInR5cCI6Ik...

eyJhbGciOiJIUzI1NiIsInR5cCI6Ik...

2. Inspecionar o que o token carrega

echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq

echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq

{
  "sub": "b1000000-0000-0000-0000-000000000001",
  "email": "admin@catalisa.app",
  "type": "access",
  "organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1",
  "permissions": ["IAM_USERS_READ", "CUSTOMERS_READ", "..."],
  "exp": 1755400000
}

{
  "sub": "b1000000-0000-0000-0000-000000000001",
  "email": "admin@catalisa.app",
  "type": "access",
  "organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1",
  "permissions": ["IAM_USERS_READ", "CUSTOMERS_READ", "..."],
  "exp": 1755400000
}

O organizationId aqui é o tenant efetivo. Todo building block tenant-scoped vai ler daqui — nunca do corpo da sua requisição.

3. Usar o token em outro building block

curl -s https://customers.stg.catalisa.app/customers/api/v1/persons \
  -H "Authorization: Bearer $TOKEN" | jq '.data | length'

curl -s https://customers.stg.catalisa.app/customers/api/v1/persons \
  -H "Authorization: Bearer $TOKEN" | jq '.data | length'

Resposta esperada — a contagem de clientes visíveis para a sua organização:

12

12

Nenhum organizationId na chamada, e ainda assim só vêm os clientes da sua organização.

4. Confirmar que o isolamento é real

curl -s -o /dev/null -w "%{http_code}\n" \
  https://customers.stg.catalisa.app/customers/api/v1/persons \
  -H "Authorization: Bearer token-invalido"

curl -s -o /dev/null -w "%{http_code}\n" \
  https://customers.stg.catalisa.app/customers/api/v1/persons \
  -H "Authorization: Bearer token-invalido"

Retorna 401. Não há caminho em que a ausência de token válido resulte em dado.

Credenciais de staging. Nunca use credencial de produção em documentação ou script de exemplo — ver AMBIENTES.md.

Criar uma organização e o primeiro administrador dela

Objetivo. Provisionar um cliente novo do zero: organização, usuário administrador e o vínculo entre os dois. Exige um token com permissões de IAM.

flowchart LR
  A["1. POST /organizations"] --> B["2. POST /users"]
  B --> C["3. GET /roles<br/>descobrir o id de ADMIN"]
  C --> D["4. POST /associations<br/>usuário + organização + papel"]
  D --> E["5. PATCH /users/:id<br/>status ativo"]
  E --> F["Administrador consegue autenticar"]

1. Criar a organização

ORG=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/organizations \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Financeira Exemplo","slug":"financeira-exemplo","type":"cliente"}')
ORG_ID=$(echo "$ORG" | jq -r '.data.id')
echo "$ORG_ID"

ORG=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/organizations \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Financeira Exemplo","slug":"financeira-exemplo","type":"cliente"}')
ORG_ID=$(echo "$ORG" | jq -r '.data.id')
echo "$ORG_ID"

Resposta esperada — o UUID da organização recém-criada:

3f6c1a02-7f4b-4c2e-9a11-0d6f9b3f1c77

3f6c1a02-7f4b-4c2e-9a11-0d6f9b3f1c77

2. Criar o usuário

USER=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/users \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"admin@financeira-exemplo.com.br","password":"UmaSenhaForte!2026"}')
USER_ID=$(echo "$USER" | jq -r '.data.id')
echo "$USER" | jq '.data | {id, email, status}'

USER=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/users \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"admin@financeira-exemplo.com.br","password":"UmaSenhaForte!2026"}')
USER_ID=$(echo "$USER" | jq -r '.data.id')
echo "$USER" | jq '.data | {id, email, status}'

Resposta esperada — repare no status, que nasce pendente:

{
  "id": "8a2f0e11-4d3b-4f18-8f0a-3b6b2c9e4d55",
  "email": "admin@financeira-exemplo.com.br",
  "status": "pendente"
}

{
  "id": "8a2f0e11-4d3b-4f18-8f0a-3b6b2c9e4d55",
  "email": "admin@financeira-exemplo.com.br",
  "status": "pendente"
}

3. Descobrir o papel

ROLE_ID=$(curl -s https://iam.stg.catalisa.app/iam/api/v1/roles \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data[] | select(.name=="ADMIN") | .id')
echo "$ROLE_ID"

ROLE_ID=$(curl -s https://iam.stg.catalisa.app/iam/api/v1/roles \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data[] | select(.name=="ADMIN") | .id')
echo "$ROLE_ID"

Resposta esperada — Role.id é inteiro, não UUID:

1

1

4. Associar usuário + organização + papel

curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/associations \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"userId\":\"$USER_ID\",\"organizationId\":\"$ORG_ID\",\"roleId\":$ROLE_ID}" | jq

curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/associations \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"userId\":\"$USER_ID\",\"organizationId\":\"$ORG_ID\",\"roleId\":$ROLE_ID}" | jq

Resposta esperada — o vínculo criado, com a chave composta dos três identificadores.

5. Ativar o usuário

curl -s -X PATCH "https://iam.stg.catalisa.app/iam/api/v1/users/$USER_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"ativo"}' | jq '.data.status'

curl -s -X PATCH "https://iam.stg.catalisa.app/iam/api/v1/users/$USER_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"ativo"}' | jq '.data.status'

Resposta esperada:

"ativo"

"ativo"

Armadilhas.

• O usuário nasce pendente e não autentica até virar ativo — faça o PATCH de status ou o login falha com 401 e ninguém entende por quê.
• Sem a associação do passo 4, o login retorna 401 mesmo com senha correta: usuário sem organização não tem contexto.
• A organização precisa ter as permissões contratadas em OrganizationPermission. Papel ADMIN numa organização sem permissões de Billing não concede nenhuma permissão de Billing — a organização é o teto.
• O slug é único globalmente. Colisão retorna 409.

Entregar credencial M2M a um parceiro

Objetivo. Dar a um parceiro acesso programático com escopo mínimo, sem senha de usuário no meio.

sequenceDiagram
  participant Você
  participant IAM
  participant Parc as Parceiro
  Você->>IAM: POST /organizations/:id/client-secret
  IAM-->>Você: clientId + clientSecret (uma única exibição)
  Você->>Parc: entrega por canal seguro (SOPS)
  Parc->>IAM: POST /oauth/token com scope reduzido
  IAM-->>Parc: access_token de 1 hora

1. Gerar o segredo

curl -s -X POST \
  "https://iam.stg.catalisa.app/iam/api/v1/organizations/$ORG_ID/client-secret" \
  -H "Authorization: Bearer $TOKEN" | jq

curl -s -X POST \
  "https://iam.stg.catalisa.app/iam/api/v1/organizations/$ORG_ID/client-secret" \
  -H "Authorization: Bearer $TOKEN" | jq

Resposta esperada — o clientSecret só aparece aqui, nunca mais:

{
  "clientId": "3f6c1a02-7f4b-4c2e-9a11-0d6f9b3f1c77",
  "clientSecret": "cs_live_8f3a...",
  "warning": "Guarde este segredo agora. Ele não será exibido novamente."
}

{
  "clientId": "3f6c1a02-7f4b-4c2e-9a11-0d6f9b3f1c77",
  "clientSecret": "cs_live_8f3a...",
  "warning": "Guarde este segredo agora. Ele não será exibido novamente."
}

2. O parceiro troca a credencial por um token

O parceiro usa assim:

curl -s -X POST https://iam.stg.catalisa.app/iam/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$ORG_ID"'",
    "client_secret": "cs_live_...",
    "scope": "CUSTOMERS_READ"
  }' | jq -r .access_token

curl -s -X POST https://iam.stg.catalisa.app/iam/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$ORG_ID"'",
    "client_secret": "cs_live_...",
    "scope": "CUSTOMERS_READ"
  }' | jq -r .access_token

Armadilhas.

• O segredo aparece uma vez. Perdeu, rotaciona — não tem recuperação.
• Rotacionar derruba a integração do parceiro na hora. Combine a janela antes.
• Sempre passe scope. Sem ele o token recebe todas as permissões da organização, o que é o oposto de privilégio mínimo.
• Guarde o segredo com SOPS, nunca em .env versionado — ver SECRETS-SOPS-REFERENCE.md.

Renovar o access token sem novo login

Objetivo. Manter a sessão viva por até sete dias sem pedir senha de novo.

sequenceDiagram
  participant App
  participant IAM
  App->>IAM: POST /oauth/token (grant_type refresh_token)
  IAM->>IAM: valida e rotaciona o refresh token
  IAM-->>App: novo access_token (1h)
  Note over App: renove antes de expirar,<br/>não depois de receber 401

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

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

Resposta esperada — repare que vem um refresh token novo: o antigo foi consumido e não serve mais.

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

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

Armadilhas.

• O refresh token vive JWT_REFRESH_EXPIRES_IN (padrão 7 dias).
• Renove antes de o access token expirar, não depois de a chamada falhar — tratar 401 como gatilho de renovação gera tempestade de renovação quando o serviço tem concorrência.
• O refresh token é de uso único e rotaciona a cada troca. Guarde o novo valor devolvido na resposta; reapresentar o antigo devolve 400 invalid_grant e gera um evento REFRESH_TOKEN_REPLAY_ATTEMPT no log de segurança.

Descobrir por que uma requisição voltou 403

Objetivo. Isolar, em quatro perguntas, qual das camadas negou a requisição. Siga na ordem — cada pergunta elimina uma causa.

flowchart TD
  Q1{"A permissão existe<br/>no vocabulário?"}
  Q1 -->|não| F1["Erro de grafia<br/>confira em /permissions/all"]
  Q1 -->|sim| Q2{"A organização contratou?"}
  Q2 -->|não| F2["Falta OrganizationPermission<br/>a organização é o teto"]
  Q2 -->|sim| Q3{"O papel concede?"}
  Q3 -->|não| F3["Troque o papel da Association"]
  Q3 -->|sim| Q4{"O token foi emitido<br/>depois da mudança?"}
  Q4 -->|não| F4["Causa mais comum:<br/>reemita o token"]
  Q4 -->|sim| F5["Investigue o requirePermission da rota"]

1. O que o token realmente carrega

echo "$TOKEN" | cut -d. -f2 | base64 -d | jq '.permissions, .organizationId'

echo "$TOKEN" | cut -d. -f2 | base64 -d | jq '.permissions, .organizationId'

Resposta esperada — a lista de permissões e o tenant efetivo do token:

["IAM_USERS_READ", "CUSTOMERS_READ"]
"2194956a-2d0a-4203-89a3-933319d80fa1"

["IAM_USERS_READ", "CUSTOMERS_READ"]
"2194956a-2d0a-4203-89a3-933319d80fa1"

2. O que a organização contratou

curl -s https://iam.stg.catalisa.app/iam/api/v1/permissions \
  -H "Authorization: Bearer $TOKEN" | jq

curl -s https://iam.stg.catalisa.app/iam/api/v1/permissions \
  -H "Authorization: Bearer $TOKEN" | jq

Se a permissão não aparecer aqui, nenhum papel vai concedê-la — a organização é o teto.

3. O vocabulário completo, para conferir a grafia exata

curl -s https://iam.stg.catalisa.app/iam/api/v1/permissions/all \
  -H "Authorization: Bearer $TOKEN" | jq

curl -s https://iam.stg.catalisa.app/iam/api/v1/permissions/all \
  -H "Authorization: Bearer $TOKEN" | jq

Armadilhas. A quarta pergunta do diagrama é a causa mais comum: permissões são resolvidas na emissão do token, então mudança de papel ou de contrato só vale no próximo token — até uma hora depois, com o padrão de JWT_EXPIRES_IN.

flowchart TD
  U["Usuário"] -->|"login"| IAM
  P["Parceiro"] -->|"client_credentials"| IAM
  IAM["IAM<br/>emite access + refresh token"] -->|"Bearer JWT"| C["Customers"]
  IAM -->|"Bearer JWT"| PY["Payments"]
  IAM -->|"Bearer JWT"| CM["Commerce"]
  IAM -->|"Bearer JWT"| B["Billing"]
  IAM -->|"Bearer JWT"| O["...os outros 27"]
  C --> N["Todos leem organizationId do token,<br/>nunca do corpo"]
  PY --> N
  CM --> N
  B --> N
  O --> N

Este diagrama é o argumento comercial da Catalisa em uma imagem: a autorização é resolvida uma vez, na borda, e vale para o catálogo inteiro. Um provedor de identidade externo pararia na primeira seta.

Variáveis de ambiente

Dependências de infraestrutura

Limites

Catálogo de erros

Observabilidade.

• GET /iam/health valida conectividade com o banco, o subsistema de senha e um round-trip completo de assinar/verificar JWT. Responde 503 se qualquer um falhar — é a sonda certa para orquestrador.
• logSecurityEvent registra LOGIN_SUCCESS, LOGIN_FAILURE e OAUTH_TOKEN_FAILURE com IP, user-agent e motivo. É a base para detectar força bruta e credencial M2M vazada.
• O JwtService.preflight() roda no startup e derruba o boot com segredo malformado.

Isolamento entre tenants

O organizationId é claim assinado no JWT. Building blocks tenant-scoped aplicam requireOrganization, que devolve 403 quando o claim está ausente. Building blocks com dado sensível somam Row-Level Security no Postgres como segunda camada, para que uma falha de aplicação não baste para vazar.

flowchart LR
  T["JWT assinado<br/>organizationId"] --> M["requireOrganization"]
  Body["Corpo da requisição"] -.->|"nunca é lido<br/>como fonte de tenant"| X["✕"]
  M --> A["Regra de negócio"]
  A --> RLS["Row-Level Security<br/>nos BBs com dado sensível"]

Credenciais em repouso

Tokens

HS256, expiração curta no access token, refresh revogável. JWT_SECRET abaixo de 256 bits impede o boot. Padrões fracos comuns geram alerta em produção.

Superfície de ataque de autenticação

Login e emissão de token passam por rate limit e vão para o log de segurança com IP e user-agent.

Exclusão lógica

Usuários e organizações usam deletedAt. O histórico sobrevive à remoção, que é o que auditoria e obrigação de retenção exigem.

LGPD

O IAM guarda e-mail e hash de senha — e-mail é dado pessoal. Exclusão é lógica por padrão; atender a pedido de eliminação exige processo explícito de expurgo, que hoje não é automatizado (ver §15).

Preciso do IAM se já uso Auth0 na minha empresa?

Sim, mas os papéis são diferentes. O Auth0 continua autenticando seus usuários; o IAM é quem os building blocks consultam para saber a organização e as permissões. A integração natural é o SSO federar o Auth0 e o IAM emitir o token que o resto da plataforma entende.

Um usuário pode pertencer a mais de uma empresa?

Pode. Association é uma tabela com chave composta de usuário, organização e papel — a mesma pessoa pode ser ADMIN numa e VIEWER em outra. No login, informe organizationId para escolher o contexto; sem isso o serviço não tem como adivinhar qual você quer.

O que acontece se o token vazar?

Ele vale até expirar — uma hora por padrão. Não há revogação de access token individual, por design: revogar exigiria consultar o banco a cada requisição. Se o vazamento for confirmado, o caminho é revogar o refresh token e, no limite, rotacionar o JWT_SECRET, o que invalida todos os tokens de uma vez.

Dá para usar em produção com autenticação só por senha?

Depende do seu risco. Hoje não há MFA (§15). Para operações reguladas, a recomendação é federar por SSO em um provedor que já tenha MFA, em vez de esperar o segundo fator nativo.

Qual a diferença entre o IAM e o API Keys?

O IAM autentica identidades — pessoas e organizações — com token de vida curta. O API Keys emite credencial de longa duração para acesso programático, com rastreio de uso próprio. Integração que roda continuamente e precisa de escopo dinâmico usa M2M do IAM; integração simples com credencial estática usa API Keys.

Por que o organizationId do login aceita slug?

Conveniência de integração. Slug é legível e estável (financeira-exemplo), o que evita carregar UUID em script de setup e documentação. A resolução acontece no AuthService, e o token sempre carrega o UUID.

Como funciona o acesso do operador de plataforma?

Pelo claim isRoot. Contas root acessam entre organizações nas rotas que, para todos os outros, exigem que o recurso pertença à organização do token. É um privilégio elevado, deve ficar restrito a poucas contas, e todo uso deve ser acompanhado pelo Audit Trail.

Adicionar um building block novo exige mudar o IAM?

Não. O building block novo declara as permissões dele no vocabulário compartilhado e usa o requirePermission de sempre. O IAM não precisa saber o que o Commerce faz — só precisa carregar as strings no token.

_{Padrão: PADRAO-DOCUMENTACAO.md · Índice: INDEX.md}