Provisionar grupos com SCIM

Pelo endpoint /Groups, um sistema de provisionamento gerencia os grupos da sua organização e os seus membros. Os grupos criados pelo SCIM são grupos comuns: eles aparecem em Grupos no console de administração, e é lá que você dá a eles acesso às aplicações, como a qualquer outro grupo.

Todos os caminhos abaixo são relativos à URL base do SCIM da sua organização. Os detalhes do protocolo comuns a usuários e grupos estão na referência da API SCIM.

Como os atributos SCIM correspondem ao BreezeAuth

Atributo SCIM	No BreezeAuth
id	O identificador do grupo no BreezeAuth.
displayName	Nome. Obrigatório.
externalId	O identificador do grupo no sistema de provisionamento. Guardado pelo BreezeAuth, não aparece no console. Único na organização.
members	Os membros diretos do grupo: usuários e outros grupos.

O Identificador do grupo é gerado pelo BreezeAuth a partir do nome quando o grupo é criado, por exemplo equipe-de-vendas para “Equipe de Vendas”, com um número acrescentado se ele já estiver em uso (equipe-de-vendas-2). Renomear o grupo depois não o altera. A Descrição do grupo não é gerenciada pelo SCIM: você pode preenchê-la no console de administração.

Membros

Cada membro é identificado pelo seu id SCIM e pelo seu type:

"members": [
  { "value": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "type": "User" },
  { "value": "9a8b7c6d-5e4f-4321-9876-0fedcba98765", "type": "Group" }
]

Campo	Descrição
value	O id de um usuário ou de outro grupo.
type	User ou Group. Obrigatório: um membro sem um type válido é recusado com 400 Bad Request.
display	Opcional e ignorado pelo BreezeAuth.

Um membro do tipo Group forma um grupo aninhado: os usuários do grupo interno se tornam membros indiretos do externo e recebem as aplicações atribuídas a ele. Um grupo não pode ser membro de si mesmo.

O SCIM só mostra e altera os membros diretos, os que foram adicionados ao próprio grupo. Os membros indiretos, que vêm de grupos aninhados, não são listados, o que também corresponde à opção Exibir somente associações diretas do console de administração.

Criar um grupo

POST /Groups
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Equipe de Vendas",
  "externalId": "grp-0042",
  "members": [{ "value": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "type": "User" }]
}

O BreezeAuth responde 201 Created com o novo grupo e o endereço dele no cabeçalho Location:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "9a8b7c6d-5e4f-4321-9876-0fedcba98765",
  "displayName": "Equipe de Vendas",
  "externalId": "grp-0042",
  "members": [{ "value": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d", "type": "User" }],
  "meta": {
    "resourceType": "Group",
    "created": "2026-10-13T14:35:12.000Z",
    "lastModified": "2026-10-13T14:35:12.000Z",
    "location": "https://api.breezeauth.com/organizations/0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d/scim/v2/Groups/9a8b7c6d-5e4f-4321-9876-0fedcba98765"
  }
}

O campo members é opcional: muitos sistemas de provisionamento criam o grupo primeiro e adicionam os membros depois.

Encontrar e ler grupos

Requisição	Retorna
GET /Groups/{id}	Um grupo, com os seus membros diretos.
GET /Groups	Todos os grupos da organização, uma página por vez, sem os membros.
GET /Groups?filter=displayName eq "Equipe de Vendas"	O grupo com esse nome, se houver.
GET /Groups?filter=externalId eq "grp-0042"	O grupo com esse identificador externo, se houver.

Para obter os membros de um grupo, leia o próprio grupo. Um grupo com mais de 1.000 membros diretos não pode ser lido nem atualizado pelo SCIM: a requisição falha com 400 Bad Request e scimType tooMany.

Atualizar um grupo

Substituir um grupo (PUT)

PUT /Groups/{id} substitui o nome, o identificador externo e os membros do grupo pelo corpo enviado. A lista de membros enviada passa a ser a lista completa de membros diretos do grupo: os membros que não estão nela são removidos, e não enviar members remove todos os membros. Se o externalId ficar de fora, ele é apagado.

Alterar alguns atributos (PATCH)

PATCH /Groups/{id} é a forma habitual de renomear um grupo e de adicionar ou remover membros sem enviar a lista inteira:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [{ "value": "b4c0d2e3-8f5a-4b7c-9d6e-0f1a2b3c4d5e", "type": "User" }]
    },
    { "op": "remove", "path": "members[value eq \"a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d\"]" }
  ]
}

As operações suportadas são:

Operação	Caminho	Efeito
add	members	Adiciona os membros de value. Membros que já estão no grupo são ignorados.
replace	members	Substitui todos os membros diretos pelos de value.
remove	members[value eq "{id}"]	Remove esse membro.
remove	members	Remove todos os membros diretos, seja qual for o conteúdo de value.
add ou replace	displayName	Renomeia o grupo.
add ou replace	externalId	Altera o identificador externo.
remove	externalId	Apaga o identificador externo.

Uma operação add ou replace também pode omitir o path e enviar um objeto em value, com displayName, externalId e members. Nessa forma, add adiciona os membros e replace os substitui.

As operações são aplicadas na ordem em que aparecem. Se uma delas falhar, por exemplo porque um membro não existe, as operações anteriores continuam aplicadas: leia o grupo para ver o estado atual antes de tentar de novo.

Excluir um grupo

DELETE /Groups/{id}

Como no console de administração, um grupo só pode ser excluído quando não tem membros. Caso contrário, a requisição falha com 409 Conflict. Remova os membros primeiro, por exemplo com uma operação remove em members, e depois exclua o grupo.

Quando o grupo é excluído, o BreezeAuth responde 204 No Content. As atribuições de aplicações do grupo são removidas com ele. Isso não pode ser desfeito.

Dar aos grupos provisionados acesso às aplicações

O SCIM não atribui aplicações. Depois que um grupo provisionado existir, atribua as aplicações dele no console de administração, uma única vez. A partir daí, todos que o sistema de provisionamento adicionar ao grupo recebem acesso automaticamente, e o perdem quando são removidos. Veja Acesso a aplicações.