---
title: "Referência da API SCIM"
description: "Contrato de endpoint SCIM 2.0 para provisionar usuários e grupos no XID.XID."
locale: "pt-BR"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/pt-br/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```shell
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. |

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

Source: https://xid.dev/pt-br/scim/index.mdx