Comece em produção
Entrar em produção na Catalisa é criar uma organização, um primeiro usuário e as permissões do que você contratou. A partir daí, o mesmo token abre todos os building blocks do catálogo.
O que você recebe ao final
O identificador da sua empresa na plataforma. É ele que separa os seus dados dos de qualquer outro cliente.
A primeira pessoa que consegue autenticar e, a partir dela, criar as demais.
A organização é o teto: nenhum usuário seu recebe permissão de um building block que você não contratou.
client_id e client_secret para que os seus sistemas falem com a plataforma sem usuário humano no meio.
O processo, passo a passo
Os passos 1 a 4 são executados pela equipe Catalisa. O passo 5 é o seu primeiro teste, e é o momento em que você confirma que está tudo de pé.
A organização é a unidade de isolamento da plataforma. O slug precisa ser único e é o que você usa no lugar do UUID em scripts e documentação.
curl -X POST https://iam.k8s.catalisa.app/iam/api/v1/organizations \
-H "Authorization: Bearer $TOKEN_OPERADOR" \
-H "Content-Type: application/json" \
-d '{
"name": "Financeira Exemplo S.A.",
"slug": "financeira-exemplo",
"type": "cliente"
}'Exige a permissão IAM_ORGANIZATIONS_CREATE. O campo type aceita cliente, parceiro ou dono.
O usuário nasce com status pendente e não autentica até ser ativado — este é o passo que mais gera confusão no primeiro acesso.
curl -X POST https://iam.k8s.catalisa.app/iam/api/v1/users \
-H "Authorization: Bearer $TOKEN_OPERADOR" \
-H "Content-Type: application/json" \
-d '{
"email": "admin@financeira-exemplo.com.br",
"password": "<senha forte definida com você>"
}'A associação liga usuário, organização e papel. Sem ela o login falha com 401 mesmo com a senha correta, porque o usuário não tem contexto de empresa.
curl -X POST https://iam.k8s.catalisa.app/iam/api/v1/associations \
-H "Authorization: Bearer $TOKEN_OPERADOR" \
-H "Content-Type: application/json" \
-d '{
"userId": "<id do passo 2>",
"organizationId": "<id do passo 1>",
"roleId": <id do papel ADMIN>
}'A organização define o teto: um usuário nunca recebe permissão que a organização dele não tem. É aqui que o que você contratou vira acesso efetivo.
As permissões seguem o formato MODULO_RECURSO_ACAO — por exemplo CUSTOMERS_READ, BILLING_INVOICES_FINALIZE, PAYMENTS_REFUND_CREATE. O vocabulário completo fica em GET /iam/api/v1/permissions/all.
A partir daqui é com você. Este é o teste que confirma que a organização, o usuário, a associação e as permissões estão todos de pé.
TOKEN=$(curl -s -X POST https://iam.k8s.catalisa.app/iam/api/v1/users/login \
-H "Content-Type: application/json" \
-d '{
"email": "admin@financeira-exemplo.com.br",
"password": "<sua senha>",
"organizationId": "financeira-exemplo"
}' | jq -r .accessToken)
# Confira o que o token carrega — o organizationId aqui é o seu tenant,
# e a lista de permissões é exatamente o que você contratou.
echo "$TOKEN" | cut -d. -f2 | base64 -d | jq '.organizationId, .permissions'O campo organizationId aceita o slug, não só o UUID. Se o login retornar 401, siga o diagnóstico da seção abaixo.
Se o primeiro login falhar
Quase toda falha de primeiro acesso é um destes quatro casos, nesta ordem de frequência.
| Sintoma | Causa provável | Como resolver |
|---|---|---|
401 com senha que você sabe estar certa | Usuário ainda em pendente | Peça a ativação — usuário nasce pendente e não autentica |
401 mesmo após ativação | Associação faltando | Usuário sem organização não tem contexto para autenticar |
Login funciona, mas tudo dá 403 | Permissões da organização não concedidas | É o passo 4 — confira em GET /iam/api/v1/permissions |
403 só em alguns building blocks | Permissão específica faltando, ou token emitido antes da concessão | Autentique de novo: permissões são resolvidas na emissão do token |
Credencial para os seus sistemas
Integração que roda sem pessoa no meio não deve usar senha de usuário. Use client_credentials: o client_id é o próprio organizationId, e o segredo é rotacionável.
curl -X POST https://iam.k8s.catalisa.app/iam/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "<seu organizationId>",
"client_secret": "<seu client_secret>",
"scope": "CUSTOMERS_READ CUSTOMERS_CREATE"
}'scope. Sem ele, o token recebe todas as permissões da organização — o oposto de privilégio mínimo. E guarde o segredo em um cofre: ele é exibido uma única vez, e rotacionar derruba a integração no instante da rotação.O cadastro self-service que falta
O processo acima funciona, mas não escala: cada cliente novo consome uma pessoa da equipe, e o passo 4 exige acesso ao banco de produção. Esta é a especificação do que precisa existir para que uma empresa entre sozinha.
As lacunas, em ordem de bloqueio
| Lacuna | Situação hoje | O que precisa existir |
|---|---|---|
| Concessão de permissão à organização | Sem rota HTTP. setPermissions e addPermission existem no serviço, mas nenhum router os expõe | PUT /iam/api/v1/organizations/:id/permissions, sob IAM_ORGANIZATIONS_UPDATE |
| Registro público | Criar organização e usuário exige token com permissão de IAM — não há rota pública | POST /iam/api/v1/signup, com rate limit, criando organização + usuário + associação em uma transação |
| Verificação de e-mail | Usuário nasce pendente, mas a ativação é manual | Token de verificação por e-mail que promove o usuário a ativo |
| Recuperação de senha | Reset é PATCH administrativo | Fluxo de token com expiração curta, por e-mail |
| Segundo fator | Campos existem no schema (mfaEnabled, mfaSecret) e o login aceita mfaCode, mas nada é verificado | Verificação TOTP de verdade antes de qualquer cadastro aberto |
| Plano contratado → permissões | Tradução é manual | Catálogo de planos no Billing que resolve automaticamente o conjunto de permissões |
Fluxo proposto
Visitante Plataforma
│
│ POST /iam/api/v1/signup
│ { empresa, cnpj, email, senha }
├────────────────────────────────▶ cria, em UMA transação:
│ Organization (status: pendente)
│ User (status: pendente)
│ Association (papel ADMIN)
│ emite token de verificação
│◀──────── 202 Accepted ──────────┤
│ envia e-mail de verificação
│
│ GET /iam/api/v1/signup/verificar?token=…
├────────────────────────────────▶ User → ativo
│ Organization → ativo
│ aplica permissões do plano
│◀──────── 200 + tokens ──────────┤
│
│ primeiro login já autenticado, com escopo do plano
▼O que não pode escapar
- Tudo em uma transação. Organização criada sem usuário, ou usuário sem associação, deixa um registro órfão que ninguém consegue acessar nem limpar pela API.
- Slug é único globalmente. Colisão precisa retornar
409com uma sugestão, não um erro genérico. - Rate limit e verificação de e-mail antes de qualquer provisionamento oneroso. Cadastro aberto é alvo de abuso automatizado no primeiro dia.
- Organização começa sem permissão nenhuma. Permissão só entra depois do plano confirmado — o padrão seguro é negar.
- Todo o fluxo registrado no Audit Trail. Quem criou, quando, de qual IP.