Referência da API SCIM

URL base

XID expõe APIs SCIM 2.0 com escopo de organização em /scim/v2/organizations/{organization_id}. Recursos de usuários e grupos são endereçados com o ID da organização no caminho.

Configure seu provedor de identidade com a URL base https://xid.dev/scim/v2/organizations/{organization_id} e o token do diretório exibido uma única vez ao criar ou rotacionar o diretório.

curl https://xid.dev/scim/v2/organizations/{organization_id}/Users \
  -H 'Authorization: Bearer scim_xxx' \
  -H 'Content-Type: application/scim+json'

Autenticação

Chamadas SCIM usam um token Bearer de diretório criado pela API de gerenciamento. O XID armazena apenas um hash do token e retorna o token em texto claro uma única vez na criação ou rotação.

Cabeçalho	Valor	Notas
`Authorization`	`Bearer scim_xxx`	Obrigatório para endpoints de usuários e grupos com escopo de organização.
`Content-Type`	`application/scim+json`	Obrigatório para solicitações POST, PUT e PATCH.
`Accept`	`application/scim+json`	Recomendado para todos os clientes SCIM.

Endpoints

Endpoint	Métodos	Uso
`/scim/v2/ServiceProviderConfig`	`GET`	Resposta ServiceProviderConfig para descoberta de clientes SCIM.
`/scim/v2/Schemas`	`GET`	Metadados de esquema de usuário e grupo.
`/scim/v2/ResourceTypes`	`GET`	Tipos de recurso SCIM compatíveis.
`/scim/v2/organizations/{organization_id}/Users`	`GET, POST`	Crie e liste usuários de diretório.
`/scim/v2/organizations/{organization_id}/Users/{id}`	`GET, PUT, PATCH, DELETE`	Leia, substitua, atualize parcialmente ou desprovisione um usuário de diretório.
`/scim/v2/organizations/{organization_id}/Groups`	`GET, POST`	Crie e liste grupos de diretório.
`/scim/v2/organizations/{organization_id}/Groups/{id}`	`GET, PUT, PATCH, DELETE`	Leia, substitua, atualize parcialmente ou remova um grupo de diretório.

Recurso de usuário

Recursos de usuário usam userName como identificador externo. Valores de e-mail, campos de nome do perfil, estado ativo e campos da extensão empresarial são preservados no perfil bruto SCIM.

Campo SCIM	Comportamento do XID
`id`	ID estável de usuário de diretório XID.
`userName`	Obrigatório. Deve ser único dentro do diretório.
`active`	`false` desprovisiona o usuário e revoga sessões ativas.
`emails`	O e-mail primário é usado para correspondência e vinculação de conta.
`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`	Armazenado e retornado para atributos empresariais como departamento.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "alice@example.com",
  "active": true,
  "name": { "givenName": "Alice", "familyName": "Lee" },
  "emails": [{ "value": "alice@example.com", "primary": true }]
}

Recurso de grupo

Recursos de grupo usam displayName como nome único do grupo no diretório. Membros referenciam IDs de usuário SCIM e são sincronizados de forma idempotente.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
    { "value": "dir_user_123", "display": "alice@example.com" }
  ]
}

Filtragem, ordenação e paginação

O XID suporta gramática de filtro SCIM com and, or, not e operadores de comparação (eq, ne, co, sw, ew, gt, ge, lt, le, pr). Expressões não suportadas retornam invalidFilter. Listas usam paginação SCIM base 1 com startIndex, count, totalResults, além de sortBy e sortOrder opcionais.

Consulta	Suporte
`filter=userName eq "alice@example.com"`	Encontre um usuário por userName.
`filter=displayName eq "Engineering"`	Encontre um grupo por displayName.
`filter=userName sw "alice" and active eq true`	Combinar operadores lógicos e de comparação.
`sortBy=userName&sortOrder=ascending`	Ordenar resultados das listas de usuários ou grupos.
`startIndex=1&count=100`	Retorne até 100 recursos a partir do primeiro resultado.
`attributes=userName,emails.value`	Retorna apenas schemas, id e os atributos SCIM solicitados.
`excludedAttributes=emails,meta`	Retorna o recurso padrão sem os atributos SCIM excluídos.

Operações em massa

POST /scim/v2/organizations/{organization_id}/Bulk aceita BulkRequest com até 100 operações e limite de 1 MiB. As respostas retornam status HTTP por operação em BulkResponse mesmo quando algumas falham.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
    {
      "method": "POST",
      "path": "/Users",
      "bulkId": "user1",
      "data": { "userName": "alice@example.com", "active": true }
    }
  ]
}

ETag and If-Match

Respostas GET de recurso incluem ETag: W/"<meta.version>" de meta.version. PUT e PATCH exigem cabeçalho If-Match com a versão atual; ausente → 428, divergência → 412.

Operações PATCH

Solicitações PATCH usam urn:ietf:params:scim:api:messages:2.0:PatchOp. O XID oferece suporte a add, replace e remove para campos de perfil graváveis e associações de grupo.

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

Respostas de erro

Erros SCIM retornam application/scim+json com o esquema SCIM Error, status HTTP, detalhe e scimType opcional.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "userName already exists"
}

Capacidades do ServiceProviderConfig

ServiceProviderConfig anuncia sort.supported=true, bulk.supported=true e etag.supported=true.
O XID expõe endpoints inbound de SCIM Service Provider para IdPs externos. Os clientes de push SCIM para SaaS downstream têm evidência local com um SaaS simulado, mas o suporte em produção ainda requer uma L4 real de administração de SaaS.

Comportamento de desprovisionamento

A rotação do token de diretório mantém o token anterior válido por uma curta janela de tolerância.
active=false e DELETE /Users/{id} desprovisiona o usuário e revoga sessões ativas.
Atualizações de associação a grupos são idempotentes. Membros desconhecidos podem ser resolvidos após o usuário chegar do provedor de identidade.