Provisionar usuários com SCIM

Pelo endpoint /Users, um sistema de provisionamento gerencia as pessoas da sua organização: os usuários que você vê em Usuários › Usuários Humanos no console de administração. Esta página explica o que cada operação SCIM faz no BreezeAuth. Os detalhes do protocolo comuns a usuários e grupos, como autenticação, filtros, paginação e erros, estão na referência da API SCIM.

Todos os caminhos abaixo são relativos à URL base do SCIM da sua organização.

O que é um usuário SCIM

Cada usuário SCIM é um usuário da sua organização. O id dele é o identificador do usuário no BreezeAuth, o mesmo valor que a API do BreezeAuth chama de membershipsUuid e que os eventos de webhook trazem. Use-o para ler, atualizar ou excluir o usuário, e para adicioná-lo a grupos.

Usuários de serviço não são pessoas: eles nunca são retornados por /Users e não podem ser alterados pelo SCIM.

Como os atributos SCIM correspondem ao BreezeAuth

Atributo SCIM	No BreezeAuth
userName	E-mail, o endereço com que a pessoa entra. Obrigatório e único na organização.
name.givenName	Nome
name.familyName	Sobrenome
displayName	Usado para preencher o nome e o sobrenome quando name não é enviado. Retornado como o nome completo.
active	Status: true para Ativo, false para Inativo. Veja Status.
externalId	O identificador da pessoa no sistema de provisionamento. Guardado pelo BreezeAuth, não aparece no console. Único na organização.
title	Cargo
emails	O endereço diferente do userName, se houver, é guardado como e-mail secundário.
phoneNumbers com type work	Telefone comercial
phoneNumbers com type mobile	Telefone
addresses	O endereço work ou, se não houver, o primeiro com dados: streetAddress, locality (cidade), region (estado) e postalCode.
photos	A foto de perfil da pessoa, a partir da primeira URL.
employeeNumber (extensão Enterprise)	Matrícula
costCenter (extensão Enterprise)	Centro de custo
organization (extensão Enterprise)	Unidade organizacional
department (extensão Enterprise)	Departamento
manager.value (extensão Enterprise)	O gestor da pessoa, como o id SCIM de outro usuário.

Os atributos da extensão Enterprise vão dentro do objeto urn:ietf:params:scim:schemas:extension:enterprise:2.0:User. Outros atributos, como password, roles, groups ou locale, são ignorados: os grupos de um usuário são gerenciados por /Groups, e os papéis apenas no console de administração.

Criar um usuário

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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "[email protected]",
  "externalId": "00u1a2b3c4",
  "name": { "givenName": "Ana", "familyName": "Souza" },
  "title": "Gerente de Contas",
  "phoneNumbers": [{ "value": "+55 11 99999-9999", "type": "mobile" }],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "4021",
    "department": "Vendas"
  }
}

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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d",
  "userName": "[email protected]",
  "externalId": "00u1a2b3c4",
  "name": { "givenName": "Ana", "familyName": "Souza", "formatted": "Ana Souza" },
  "displayName": "Ana Souza",
  "active": true,
  "title": "Gerente de Contas",
  "emails": [{ "value": "[email protected]", "type": "work", "primary": true }],
  "phoneNumbers": [{ "value": "+55 11 99999-9999", "type": "mobile" }],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "4021",
    "department": "Vendas"
  },
  "meta": {
    "resourceType": "User",
    "created": "2026-10-13T14:32:05.000Z",
    "lastModified": "2026-10-13T14:32:05.000Z",
    "location": "https://api.breezeauth.com/organizations/0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d/scim/v2/Users/a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d"
  }
}

O userName é obrigatório. Se name não for enviado, o BreezeAuth divide o displayName em nome e sobrenome e, em último caso, usa a parte do e-mail antes do @.

O que acontece em seguida depende do endereço de e-mail, exatamente como quando um administrador adiciona um usuário:

Endereço de e-mail	Resultado
Em um dos seus domínios verificados	Um usuário gerenciado, Ativo na hora. A pessoa recebe um e-mail de boas-vindas.
Em qualquer outro domínio	Um convidado, Pendente até aceitar o convite que recebe por e-mail. Até lá, o SCIM o retorna com active: false. Veja Convites.

Se active for false na requisição, o usuário é criado e logo em seguida desativado.

Encontrar e ler usuários

Requisição	Retorna
GET /Users/{id}	Um usuário.
GET /Users	Todos os usuários da organização, uma página por vez.
GET /Users?filter=userName eq "[email protected]"	O usuário com esse endereço de e-mail, se houver.
GET /Users?filter=externalId eq "00u1a2b3c4"	O usuário com esse identificador externo, se houver.

Os sistemas de provisionamento costumam buscar com um desses filtros antes de criar um usuário, para evitar duplicatas. Lembre-se de codificar o filtro para URL na query string. A paginação e os outros parâmetros estão descritos na referência.

Como os status aparecem

O SCIM só sabe se um usuário está ativo. Os status do BreezeAuth aparecem assim:

Status no BreezeAuth	active
Ativo	true
Inativo, Pendente, Convite recusado, Revisão pendente	false

Atualizar um usuário

Substituir um usuário (PUT)

PUT /Users/{id} substitui o usuário inteiro pelo corpo enviado, que tem o mesmo formato da criação. Todo atributo que você deixar de fora é apagado no BreezeAuth e, se active ficar de fora, o usuário passa a ser Ativo. Envie o usuário completo toda vez, ou use PATCH para alterar apenas alguns atributos.

Alterar alguns atributos (PATCH)

PATCH /Users/{id} aplica uma lista de operações, seguindo o padrão SCIM:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "title", "value": "Diretora de Vendas" },
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department",
      "value": "Comercial"
    },
    { "op": "remove", "path": "phoneNumbers[type eq \"mobile\"].value" }
  ]
}

Cada operação tem um op (add, replace ou remove), um path e, exceto em remove, um value. Os caminhos suportados são:

Caminho	add / replace	remove
active	Sim	Não
userName ou emails[type eq "work"].value	Sim	Não
name.givenName, name.familyName	Sim	Não
displayName (dividido em nome e sobrenome)	Sim	Não
externalId	Sim	Sim
title	Sim	Sim
phoneNumbers[type eq "work"].value, phoneNumbers[type eq "mobile"].value	Sim	Sim
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User: seguido de employeeNumber, costCenter, organization, department, manager ou manager.value	Sim	Sim

Uma operação add ou replace também pode omitir o path e enviar um objeto em value, por exemplo { "op": "replace", "value": { "active": false } }. Nessa forma, o BreezeAuth aceita active, userName, externalId, name, displayName, title e o objeto da extensão Enterprise. Endereços, e-mails secundários e fotos só podem ser alterados com PUT.

Todas as operações de uma requisição são aplicadas juntas: se uma delas for inválida, nada é alterado.

Alterar o endereço de e-mail de um usuário

Alterar o userName segue as mesmas regras do console de administração:

• Usuários gerenciados: o novo endereço precisa estar em um dos seus domínios verificados. A conta da pessoa no BreezeAuth também é atualizada.
• Convidados: o endereço de e-mail não pode ser alterado, e a requisição falha com 400 Bad Request. Para mudar um convidado de endereço, crie um novo usuário e exclua o antigo.

Desativar um usuário

Para remover o acesso de alguém mantendo o registro, defina active como false:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{ "op": "replace", "path": "active", "value": false }]
}

O usuário passa a ser Inativo, com o mesmo efeito de desativá-lo no console de administração: um usuário gerenciado não consegue mais entrar no BreezeAuth, e um convidado não consegue mais usar as aplicações da sua organização. Os grupos e as atribuições de aplicações dele são mantidos. Defina active de novo como true para restaurar o acesso.

Excluir um usuário

DELETE /Users/{id}

O BreezeAuth responde 204 No Content. Como ao excluir no console de administração, o usuário é removido de todos os seus grupos e aplicações e, no caso de um usuário gerenciado, a conta dele no BreezeAuth também é excluída. Isso não pode ser desfeito.

O que o SCIM não pode alterar

• Proprietários. Usuários com o papel Proprietário não podem ser alterados nem excluídos pelo SCIM: a requisição falha com 401 Unauthorized. Gerencie-os no console de administração.
• Papéis. O SCIM nunca dá nem remove papéis administrativos.
• Status além de ativo e inativo. Um sistema de provisionamento não pode voltar um usuário para Pendente ou Revisão pendente.
• Senhas, MFA e sessões. Pertencem à pessoa e às ferramentas de segurança da conta da sua organização.