Referência da API SCIM

Esta página documenta os endpoints SCIM 2.0 que a axe Account expõe para provisionamento de usuários e grupos. Na maioria dos casos, o conector SCIM do seu provedor de identidade chama esses endpoints para você; esta referência é destinada a equipes que constroem uma integração personalizada ou validam o comportamento diretamente.

A axe implementa o padrão SCIM 2.0 (RFC 7643 / RFC 7644). Esta página foca no comportamento específico da axe. Para o protocolo genérico, consulte as especificações SCIM.

URL base e autenticação

Todos os endpoints são servidos sob /api/scim/v2 no seu URL base regional ou privado:

https://axe.deque.com/api/scim/v2

Autentique todas as solicitações com sua chave de API SCIM:

-H "X-API-Key: <API_KEY>"
# or
-H "Authorization: <API_KEY>"

Veja Pré-requisitos e Configuração para obter uma chave e o URL base.

Convenções

• Tipo de conteúdo: application/json
• Respostas de erro usa o esquema de erro SCIM:

  {
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
    "detail": "<message>",
    "status": <code>
  }

• Paginação (Usuários): startIndex (baseada em 1) e count (1–100).
• Filtragem (Usuários, Grupos): filter usando o operador eq, por exemplo, userName eq "user@example.com".

Usuários

Listar usuários

GET /api/scim/v2/Users

Retorna membros da sua empresa. Suporta paginação e filtragem.

Parâmetros de consulta

Exemplo

curl -H "X-API-Key: $KEY" \
  "https://axe.deque.com/api/scim/v2/Users?count=10&startIndex=1"

Resposta 200 OK

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 42,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "5f3e...c2",
      "userName": "user@example.com",
      "active": true,
      "name": { "givenName": "Alex", "familyName": "Doe" },
      "emails": [
        { "primary": true, "value": "user@example.com", "type": "work", "display": "user@example.com" }
      ],
      "groups": [
        { "value": "grp-1", "display": "Axe Monitor", "$ref": "/Groups/grp-1" }
      ],
      "meta": { "resourceType": "User", "location": "/Users/5f3e...c2" }
    }
  ]
}

Erros

Obter um usuário

GET /api/scim/v2/Users/{id}

Retorna um único usuário pelo seu ID de usuário axe. active reflete a associação à empresa.

Resposta 200 OK — um recurso de Usuário (veja acima).

Erros

Criar um usuário

POST /api/scim/v2/Users

Provisiona um usuário: cria a conta axe, adiciona-o à sua empresa e envia um e-mail de convite. Um valor groups no corpo é ignorado — atribua o acesso ao produto separadamente via PATCH /Groups.

Corpo da solicitação

Exemplo

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "user@example.com",
    "name": { "givenName": "Alex", "familyName": "Doe" },
    "emails": [{ "type": "work", "value": "user@example.com", "primary": true }],
    "active": true
  }' \
  "https://axe.deque.com/api/scim/v2/Users"

Resposta 201 Created — o recurso de Usuário criado.

Erros

Substituir um usuário

PUT /api/scim/v2/Users/{id}

Atualiza o nome e o e-mail de um usuário.

Corpo da solicitação

Resposta 200 OK — o recurso de Usuário atualizado.

Erros

Ativar ou desativar um usuário

PATCH /api/scim/v2/Users/{id}

Define a associação à empresa. active: true adiciona o usuário à empresa; active: false o desativa (remove a associação; a conta é mantida).

Corpo da solicitação

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

Resposta 204 No Content

Erros

Desativar um usuário

DELETE /api/scim/v2/Users/{id}

Remove o usuário de sua empresa (remoção leve — a conta é mantida).

Resposta 204 No Content

Erros

Grupos

Os grupos são assinaturas de produtos (concedem acesso a um produto) ou equipes (organizam os usuários). Veja Como o SCIM Funciona com a Conta axe.

Listar grupos

GET /api/scim/v2/Groups

Retorna todas as assinaturas de produtos e equipes de sua empresa. Este endpoint não é paginado.

Parâmetros de consulta

Resposta 200 OK

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "startIndex": 1,
  "itemsPerPage": 5,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "grp-1",
      "displayName": "Axe Monitor",
      "members": [
        { "value": "5f3e...c2", "display": "user@example.com", "$ref": "/Users/5f3e...c2" }
      ]
    }
  ]
}

Obter um grupo

GET /api/scim/v2/Groups/{id}

Resposta 200 OK — um recurso de Grupo.

Erros

Criar um grupo

POST /api/scim/v2/Groups

Cria uma equipe. Se displayName corresponder exatamente ao nome de um produto para o qual sua empresa possui uma assinatura ativa, nenhuma equipe é criada — o grupo de assinaturas de produtos existente é retornado em vez disso (201, com suas id e Location), e quaisquer members no corpo da solicitação são ignorados. Gerencie a associação desse grupo através de PATCH /Groups/{id}.

A correspondência diferencia maiúsculas e minúsculas e é exata. Se o nome corresponder a um produto cuja assinatura não não está ativa, uma equipe regular é criada com esse nome — ela não concederá acesso ao produto.

Corpo da solicitação

Resposta 201 Created — o recurso de Grupo criado, com um cabeçalho Location.

Erros

Atualizar a participação no grupo

PATCH /api/scim/v2/Groups/{id}

Adiciona ou remove membros. Para um grupo de assinatura, isso concede ou revoga um assento de produto. Para um grupo de equipe, isso altera a participação na equipe.

Corpo da solicitação

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "add", "path": "members", "value": [ { "value": "5f3e...c2" } ] }
  ]
}

Use op: "remove" com um path para remover membros. Um replace com um array vazio remove todos os membros.

Resposta 204 No Content

Erros

Excluir um grupo

DELETE /api/scim/v2/Groups/{id}

Exclui um equipe. Solicitações de exclusão contra um grupo de assinatura de produto são ignoradas (retorna 204).

Resposta 204 No Content

Erros

Atualizar um grupo (não suportado)

PUT /api/scim/v2/Groups/{id}

Não suportado. Retorna 405 Method not allowed. Use PATCH para modificar a participação.

Pontos de descoberta

Esses suportam a configuração automática do conector. Todos retornam 200 OK.

Relacionado

• Como o SCIM funciona com a conta axe
• Configurando seu Provedor de Identidade
• Resolução de problemas