Riferimento API SCIM

Questa pagina documenta gli endpoint SCIM 2.0 che axe Account espone per il provisioning di utenti e gruppi. Nella maggior parte dei casi, il connettore SCIM del tuo provider di identità chiama questi endpoint per te; questo riferimento è per i team che costruiscono un'integrazione personalizzata o validano il comportamento direttamente.

axe implementa lo standard SCIM 2.0 (RFC 7643 / RFC 7644). Questa pagina si concentra sul comportamento specifico di axe. Per il protocollo generico, fare riferimento alle specifiche SCIM.

URL di base e autenticazione

Tutti gli endpoint sono serviti sotto /api/scim/v2 sul tuo URL di base regionale o privato:

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

Autentica ogni richiesta con la tua chiave API SCIM:

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

Vedi Prerequisiti e configurazione per ottenere una chiave e un URL di base.

Convenzioni

• Tipo di contenuto: application/json
• Risposte di errore utilizzano lo schema d’errore SCIM:

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

• Paginazione (Utenti): startIndex (basato su 1) e count (1–100).
• Filtraggio (Utenti, Gruppi): filter usando l'operatore eq, ad es. userName eq "user@example.com".

Utenti

Elenco utenti

GET /api/scim/v2/Users

Restituisce i membri della tua impresa. Supporta la paginazione e il filtraggio.

Parametri di query

Esempio

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

Risposta 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" }
    }
  ]
}

Errori

Ottieni un utente

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

Restituisce un singolo utente tramite il loro ID utente axe. active riflette l'appartenenza all'impresa.

Risposta 200 OK — una risorsa Utente (vedi sopra).

Errori

Crea un utente

POST /api/scim/v2/Users

Configura un utente: crea l'account axe, lo aggiunge alla tua impresa e invia un'email di invito. Un valore groups nel corpo è ignorato — assegna l'accesso ai prodotti separatamente tramite PATCH /Gruppi.

Corpo della richiesta

Esempio

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"

Risposta 201 Created — la risorsa Utente creata.

Errori

Sostituisci un utente

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

Aggiorna il nome e l'email di un utente.

Corpo della richiesta

Risposta 200 OK — la risorsa Utente aggiornata.

Errori

Attivare o disattivare un utente

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

Imposta l'iscrizione aziendale. active: true aggiunge l'utente all'azienda; active: false lo disattiva (rimuove l'iscrizione; l'account è conservato).

Corpo della richiesta

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

Risposta 204 No Content

Errori

Disattivare un utente

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

Rimuove l'utente dalla tua azienda (rimozione soft — l'account è conservato).

Risposta 204 No Content

Errori

Gruppi

I gruppi sono o abbonamenti ai prodotti (assegna un posto prodotto) o squadre (organizza utenti). Vedi Come SCIM funzioni con l'account axe.

Elenca gruppi

GET /api/scim/v2/Groups

Restituisce tutti gli abbonamenti ai prodotti e le squadre per la tua azienda. Questo endpoint non è paginato.

Parametri di query

Risposta 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" }
      ]
    }
  ]
}

Ottieni un gruppo

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

Risposta 200 OK — una risorsa Gruppo.

Errori

Crea un gruppo

POST /api/scim/v2/Groups

Crea una squadra. Se displayName corrisponde esattamente al nome di un prodotto per cui la tua azienda ha un abbonamento attivo, non viene creata alcuna squadra — viene invece restituito il gruppo di abbonamenti ai prodotti esistente (201, con i suoi id e Location), e qualsiasi members nel corpo della richiesta viene ignorato. Gestisci l'iscrizione di quel gruppo tramite PATCH /Groups/{id}.

Il confronto è sensibile e preciso. Se il nome corrisponde a un prodotto il cui abbonamento è non attivo, viene creata invece una squadra regolare con quel nome — non concederà posti prodotto.

Corpo della richiesta

Risposta 201 Created — la risorsa del Gruppo creato, con un'intestazione Location.

Errori

Aggiorna l'affiliazione al gruppo

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

Aggiunge o rimuove membri. Per gruppo di iscrizione, concede o revoca un posto per il prodotto. Per gruppo del team, modifica l'affiliazione al team.

Corpo della richiesta

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

Usa op: "remove" con path per rimuovere membri. Un replace con un array vuoto rimuove tutti i membri.

Risposta 204 No Content

Errori

Elimina un gruppo

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

Elimina un team. Le richieste di eliminazione su un gruppo di iscrizione al prodotto sono ignorate (ritorna 204).

Risposta 204 No Content

Errori

Aggiorna un gruppo (non supportato)

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

Non supportato. Ritorna 405 Method not allowed. Usa PATCH per modificare l'affiliazione.

Endpoint di scoperta

Supportano la configurazione automatica dei connettori. Tutti ritornano 200 OK.

Correlato

• Come funziona SCIM con axe Account
• Configurare il tuo Fornitore di Identità
• Risoluzione dei problemi