Pular para o conteúdo principal

Associations

Gerenciamento de associacoes entre usuários, organizacoes e roles.

Endpoints​

MétodoEndpointDescriçãoPermissão
POST/api/v1/associationsAtribuir role a usuárioIAM_ASSOCIATIONS_CREATE
DELETE/api/v1/associationsRemover role de usuárioIAM_ASSOCIATIONS_DELETE
GET/api/v1/users/:id/associationsListar associações do usuárioIAM_ASSOCIATIONS_READ
GET/api/v1/organizations/:id/membersListar membros da organizaçãoIAM_ASSOCIATIONS_READ

Conceito​

Uma association vincula:

  • Um usuário (userId)
  • A uma organização (organizationId)
  • Com uma role específica (roleId)

Um usuário pode ter multiplas associacoes com diferentes organizacoes e roles.

Exemplo de múltiplas associações:

  • Usuário A pode estar vinculado a:

    • Organização 1 com role ADMIN
    • Organização 2 com role VIEWER

  • Usuário B pode estar vinculado a:

    • Organização 1 com role CUSTOMER_MANAGER

Isso permite que um mesmo usuário tenha diferentes níveis de acesso em diferentes organizações da plataforma.

Atribuir Role a Usuário​

POST /api/v1/associations

Cria uma nova associacao entre usuário, organização e role.

Request​

CampoTipoObrigatórioDescrição
userIdstring (UUID)SimID do usuário
organizationIdstring (UUID)SimID da organização
roleIdintegerSimID da role
IDs das Roles
IDRole
1ADMIN
2CUSTOMER_MANAGER
3DECISION_MANAGER
4DOCUMENT_OPERATOR
5FILE_MANAGER
6IAM_MANAGER
7PRICING_MANAGER
8PRODUCT_MANAGER
9VERIFICATION_OPERATOR
10VIEWER
11WEBHOOK_MANAGER
curl -X POST 'https://iam.stg.catalisa.app/api/v1/associations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "organizationId": "550e8400-e29b-41d4-a716-446655440000",
    "roleId": 1
  }'

Response (201 Created)​

{
  "data": {
    "type": "associations",
    "id": "assoc-uuid",
    "attributes": {
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "organizationId": "550e8400-e29b-41d4-a716-446655440000",
      "roleId": 1,
      "roleName": "ADMIN",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/associations/assoc-uuid"
    }
  }
}

Remover Role de Usuário​

DELETE /api/v1/associations

Remove uma associação existente.

Request​

CampoTipoObrigatórioDescrição
userIdstring (UUID)SimID do usuário
organizationIdstring (UUID)SimID da organização
roleIdintegerSimID da role
curl -X DELETE 'https://iam.stg.catalisa.app/api/v1/associations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "organizationId": "550e8400-e29b-41d4-a716-446655440000",
    "roleId": 1
  }'

Response (204 No Content)​

Sem corpo de resposta.

Listar Associações do Usuário​

GET /api/v1/users/:userId/associations

Lista todas as associações de um usuário específico.

Query Parameters​

ParâmetroTipoDescrição
page[number]integerNúmero da página
page[size]integerItens por página
filter[organizationId]stringFiltrar por organização
filter[roleId]integerFiltrar por role
curl 'https://iam.stg.catalisa.app/api/v1/users/550e8400-e29b-41d4-a716-446655440001/associations' \
  -H 'Authorization: Bearer SEU_TOKEN'

Response (200 OK)​

{
  "data": [
    {
      "type": "associations",
      "id": "assoc-uuid-1",
      "attributes": {
        "userId": "550e8400-e29b-41d4-a716-446655440001",
        "organizationId": "550e8400-e29b-41d4-a716-446655440000",
        "roleId": 1,
        "roleName": "ADMIN",
        "createdAt": "2024-01-15T10:30:00Z"
      },
      "organization": {
        "type": "organizations",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "attributes": {
          "name": "Empresa ABC",
          "slug": "empresa-abc"
        }
      },
      "role": {
        "type": "roles",
        "id": "1",
        "attributes": {
          "name": "ADMIN"
        }
      }
    }
  ],
  "meta": {
    "totalItems": 2,
    "totalPages": 1,
    "currentPage": 1
  }
}

Listar Membros da Organização​

GET /api/v1/organizations/:organizationId/members

Lista todos os membros (usuários associados) de uma organização.

Query Parameters​

ParâmetroTipoDescrição
page[number]integerNúmero da página
page[size]integerItens por página
filter[roleId]integerFiltrar por role
curl 'https://iam.stg.catalisa.app/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/members' \
  -H 'Authorization: Bearer SEU_TOKEN'

Response (200 OK)​

{
  "data": [
    {
      "type": "associations",
      "id": "assoc-uuid-1",
      "attributes": {
        "userId": "550e8400-e29b-41d4-a716-446655440001",
        "organizationId": "550e8400-e29b-41d4-a716-446655440000",
        "roleId": 1,
        "roleName": "ADMIN"
      },
      "user": {
        "type": "users",
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "attributes": {
          "email": "admin@empresa.com",
          "status": "ativo"
        }
      },
      "role": {
        "type": "roles",
        "id": "1",
        "attributes": {
          "name": "ADMIN"
        }
      }
    },
    {
      "type": "associations",
      "id": "assoc-uuid-2",
      "attributes": {
        "userId": "550e8400-e29b-41d4-a716-446655440002",
        "organizationId": "550e8400-e29b-41d4-a716-446655440000",
        "roleId": 10,
        "roleName": "VIEWER"
      },
      "user": {
        "type": "users",
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "attributes": {
          "email": "viewer@empresa.com",
          "status": "ativo"
        }
      }
    }
  ],
  "meta": {
    "totalItems": 2,
    "totalPages": 1,
    "currentPage": 1
  }
}

Casos de Uso Comuns​

Adicionar Usuário como Admin de uma Organização​

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

const { data: user } = await userResponse.json();

// 2. Associar como ADMIN (roleId: 1)
await fetch('https://iam.stg.catalisa.app/api/v1/associations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: user.id,
    organizationId: 'org-id',
    roleId: 1,
  }),
});

Mudar Role de um Usuário​

const userId = 'user-id';
const orgId = 'org-id';

// 1. Remover role antiga (VIEWER)
await fetch('https://iam.stg.catalisa.app/api/v1/associations', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId,
    organizationId: orgId,
    roleId: 10, // VIEWER
  }),
});

// 2. Adicionar role nova (CUSTOMER_MANAGER)
await fetch('https://iam.stg.catalisa.app/api/v1/associations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId,
    organizationId: orgId,
    roleId: 2, // CUSTOMER_MANAGER
  }),
});

Erros Comuns​

CódigoErroDescrição
400VALIDATIONCampos obrigatórios ausentes
404NOT_FOUNDUsuário, organização ou role não encontrado
409CONFLICTAssociação já existe