# Accounts synchroniseren met Zivver via SCIM 2.0

## Introductie

Dit artikel legt uit hoe je direct kunt communiceren met het Zivver SCIM V2 API-eindpunt. Je kunt deze informatie gebruiken als je organisatie Zivver-accounts automatisch wil beheren door een eigen SCIM-koppeling te bouwen.

Info

Gebruik het Zivver SCIM V2 API-endpoint niet om verbinding te maken met bestaande SCIM-endpoints zoals Entra ID of Google Workspaces. Deze beperking bestaat omdat geautomatiseerde accountprovisioning vanuit een van deze systemen de [Zivver Synctool](https://docs.zivver.com/nl/admin/synctool-v2/synctool-manual.html) vereist.

## Accountmanagement in Zivver

Zivver-accounts kun je handmatig beheren via het [Zivver-beheerportaal](https://app.zivver.com/organization/accounts), of automatisch via de Zivver System for Cross-domain Identity Management (SCIM) API. Zivver volgt de SCIM 2.0-specificaties. Voor organisaties met meer dan 100 medewerkers adviseert Zivver om het accountbeheer te automatiseren. Zivver raadt hiervoor de [Zivver Synctool](https://docs.zivver.com/nl/admin/synctool-v2/synctool-manual.html) aan.

Zivver maakt onderscheid tussen normale accounts en functionele accounts. Elk accounttype wordt op een andere manier beheerd, en beide typen worden in deze handleiding uitgelegd.

| **Accounttype** | **Beschrijving** |
| --- | --- |
| Normaal | Persoonlijk account waarop een gebruiker kan inloggen. |
| Functioneel | Gedeeld account waarop je niet rechtstreeks kunt inloggen. Met [Gedelegeerde toegang](https://docs.zivver.com/nl/admin/webapp/references/account-delegation.html) kan een gebruiker Zivver-berichten versturen en ontvangen vanuit een functioneel account. |

## Verbinding maken met het Zivver SCIM v2-eindpunt

| **Verbinding** |  |
| --- | --- |
| URL | `https://app.zivver.com/api/scim/v2/` |
| Port | `443` |

De verbinding wordt geauthenticeerd met een [Bearer Token](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1). Een Zivver-beheerder kan hiervoor een API-sleutel aanmaken in het [Zivver-beheerportaal](https://app.zivver.com/organization/api-keys). Een SCIM-client moet de in Zivver gegenereerde API-sleutel als token meesturen in de **Authorization**-header, zoals beschreven in [RFC6750 sectie 2.1](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1):

> Clients SHOULD make authenticated requests with a bearer token using the “Authorization” request header field with the “Bearer” HTTP authorization scheme.

Voorbeeld:

> Authorization: Bearer {base64-gecodeerde Zivver API-sleutel}

Info

**Het bearer token coderen in base64**

De HTTP-specificaties vereisen dat de client het bearer token in base64 codeert. Bestaande tools of libraries doen dit meestal automatisch.

## Ondersteunde SCIM-bewerkingen

De volgende SCIM-bewerkingen worden ondersteund door het Zivver SCIM v2-eindpunt:

- Create: POST `https://app.zivver.com/api/scim/v2/{resource}`
- Read: GET `https://app.zivver.com/api/scim/v2/{resource}/{id}`
- Replace: PUT `https://app.zivver.com/api/scim/v2/{resource}/{id}`
- Delete: DELETE `https://app.zivver.com/api/scim/v2/{resource}/{id}`
- Update: PATCH `https://app.zivver.com/api/scim/v2/{resource}/{id}`
- Search: GET `https://app.zivver.com/api/scim/v2/{resource}`

Waarschuwing

**Delete: DELETE**

Het verwijderen van Zivver-accounts is onomkeerbaar. Verwijderde gegevens kunnen niet worden teruggezet. Zivver adviseert om de waarde van het attribuut `active` op `false` te zetten (suspend) in plaats van het account te verwijderen.

Info

**Update: PATCH**

De ondersteuning voor deze bewerking is beperkt tot Microsoft Entra ID. Voor andere clients wordt geadviseerd om in plaats daarvan de PUT-bewerking te gebruiken.

## Zivver-gebruikersaccounts beheren

Je kunt inloggen op een Zivver-gebruikersaccount met een Zivver-wachtwoord of via [Single Sign-On (SSO)](https://docs.zivver.com/nl/admin/sso/sso-intro.html). Zivver gebruikt het SCIM-resourcetype **Users** om gebruikersaccounts te beheren, gebaseerd op het volgende schema:

**urn:ietf:params:scim:schemas:core:2.0:User**

Het user-object moet [common attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-3.1) en [singular attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.1) bevatten. Daarnaast gebruikt Zivver [multi-value attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.2), de [enterprise user schema extension](https://datatracker.ietf.org/doc/html/rfc7643#section-4.3) en een [custom extension schema](https://datatracker.ietf.org/doc/html/rfc7643#section-3.3).

### Gemeenschappelijke user-objectattributen

[RFC-7643: Common Attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-3.1)

De volgende gemeenschappelijke user-objectattributen worden door Zivver geleverd en kunnen niet worden aangepast.

- **id**: unieke identifier die door Zivver wordt verstrekt

_\_De id wordt door Zivver verstrekt en kan niet worden aangepast. De `{id}` wordt gebruikt voor SCIM-bewerkingen._

- **meta.resourceType**: user

- **meta.created**: aanmaakdatum van het account

_\_De aanmaakdatum wordt door Zivver verstrekt en kan niet worden aangepast._

- **meta.location**: `/scim/v2/Users/{id}`

### Enkelvoudige user-objectattributen

[RFC-7643: Singular attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.1)

Zivver gebruikt de volgende verplichte en optionele enkelvoudige attributen.

- **userName**: primair e-mailadres (verplicht)

_\_Zivver identificeert een account aan de hand van het primaire e-mailadres._

- **name.formatted**: weergavenaam (verplicht)

_\_Zivver gebruikt deze naam om ontvangers te tonen wie een bericht heeft verzonden. Vul dit veld bij voorkeur met een voornaam en achternaam._

- **nickName**: bijnaam (optioneel)

_\_Zivver gebruikt deze waarde in de aanhef van notificatieberichten._

- **active**: of het account actief of geschorst is (verplicht)

_\_Zivver gebruikt dit attribuut om accounts te schorsen. Schors een account wanneer een medewerker uit dienst gaat. Een geschorste gebruiker wordt opnieuw geactiveerd wanneer de waarde `true` is._

### Multi-value user-objectattributen

[RFC-7643: Multi-value attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.2)

Zivver gebruikt de volgende optionele multi-value attributen.

- **phoneNumbers**: het eerste telefoonnummer in de lijst wordt gebruikt voor 2FA (optioneel)

_\_Zorg ervoor dat dit nummer sms-berichten kan ontvangen._

### Enterprise User Schema Extension

[RFC-7643: Enterprise user schema extension](https://datatracker.ietf.org/doc/html/rfc7643#section-4.3)

Zivver gebruikt het volgende extra attribuut wanneer je organisatie met [Organisatie-Eenheden](https://docs.zivver.com/nl/admin/webapp/organizational-units.html) werkt.

**urn:ietf:params:scim:schemas:extension:enterprise:2.0:User**

- **division**: de Organisatie-Eenheid waartoe het account behoort (optioneel)

_\_Zivver gebruikt dit attribuut om het account aan de juiste Organisatie-Eenheid te koppelen._

Info

**Hoe weet ik of mijn organisatie Organisatie-Eenheden gebruikt?**

Als dit zo is, heb je toegang tot de pagina [Organisatie-Eenheden](https://app.zivver.com/organization/units). Heb je geen toegang, dan gebruikt je organisatie deze functie niet of heb je geen beheerdersrechten.

### Zivver’s Custom Extension Schema

[RFC-7643: Custom schema extension](https://datatracker.ietf.org/doc/html/rfc7643#section-3.3)

Zivver breidt de bovenstaande attributen uit met het volgende schema:

**urn:ietf:params:scim:schemas:zivver:0.1:User**

Dit schema bevat de volgende attributen:

- **password**: Zivver-wachtwoord wanneer SSO niet wordt gebruikt (verplicht tenzij SSO wordt gebruikt)

_\_Dit wachtwoord wordt gebruikt om de encryptiesleutels te genereren. Het wachtwoord is alleen nodig voor de **eerste login**; daarna maakt de gebruiker een eigen wachtwoord._

- **SsoAccountKey**: ZivverAccountKey wanneer SSO wordt gebruikt (verplicht bij SSO)

_\_Dit attribuut wordt gebruikt om de encryptiesleutels te genereren._

Info

**Belangrijke informatie over de ZivverAccountKey**

Deze waarde moet lang, uniek en random zijn. Bij voorkeur genereert je organisatie deze sleutel zelf. Als alternatief kan `objectGUID` worden gebruikt, maar dit vormt een beveiligingsrisico omdat deze waarde vaak in meerdere systemen wordt hergebruikt. Gebruik geen `objectSID` of vergelijkbare AD-attributen omdat deze voorspelbaar zijn.

- **aliases**: lijst met e-mailaliassen (optioneel)

_\_De gebruiker kan Zivver-berichten ontvangen op deze aliassen._

- **delegates**: lijst met e-mailadressen die volledige toegang hebben (optioneel)

_\_Gebruikers kunnen berichten lezen en verzenden namens andere accounts._

Info

**Belangrijke informatie over delegates**

**delegates** is een lijst van e-mailadressen, niet van user-`{id}`ʼs.

### Voorbeeld van minimale user-representatie

Het volgende is een niet-normatief voorbeeld van de minimale vereiste SCIM-representatie in JSON-formaat.

```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:zivver:0.1:User"],
  "meta": {
    "resourceType": "User",
    "created": "2010-01-23T04:56:22Z",
    "location": "/scim/v2/Users/2819c223-7f76-453a-919d-413861904646"
  },
  "active": true,
  "id": "2819c223-7f76-453a-919d-413861904646",
  "name": {
    "formatted": "Barbara Jensen"
  },
  "urn:ietf:params:scim:schemas:zivver:0.1:User": {
    "SsoAccountKey": "48452ce3-9346-4ef0-9528-19btf6d4e545"
  },
  "userName": "bjensen@example.com"  
}
```

### Voorbeeld van volledige user-representatie

Het volgende is een niet-normatief voorbeeld van een volledig ingevulde SCIM-userrepresentatie in JSON-formaat.

```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "urn:ietf:params:scim:schemas:zivver:0.1:User"],
  "meta": {
    "resourceType": "User",
    "created": "2010-01-23T04:56:22Z",
    "location": "/scim/v2/Users/2819c223-7f76-453a-919d-413861904646"
  },
  "active": true,
  "id": "2819c223-7f76-453a-919d-413861904646",
  "name": {
    "formatted": "Barbara Jensen"
  },
  "nickName": "Babs Jensen",
  "phoneNumbers": [
    {"value":"555-555-5555"}
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "division": "Development"
  },
  "urn:ietf:params:scim:schemas:zivver:0.1:User": {
    "SsoAccountKey": "48452ce3-9346-4ef0-9528-19btf6d4e545",
    "aliases": ["barbarajensen@example.com", "barbara.jensen@example.com"],
    "delegates": ["jdoe@example.com", "hpeterson@example.com"]
  },
  "userName": "bjensen@example.com"
}
```

## Functionele Zivver-accounts beheren

Functionele Zivver-accounts zijn gedeelde accounts. Als je Zivver-gebruikersaccount gedelegeerde toegang heeft tot een functioneel account, word je automatisch ingelogd op dat functionele account. In Zivver wordt het SCIM-resourcetype **Groups** gebruikt, gebaseerd op het volgende schema:

**urn:ietf:params:scim:schemas:core:2.0:Group**

Het group-object moet een [common attribute](https://datatracker.ietf.org/doc/html/rfc7643#section-3.1), een [singular attribute](https://datatracker.ietf.org/doc/html/rfc7643#section-4.2) en een [multi-value attribute](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.2) bevatten. Daarnaast gebruikt Zivver de [enterprise user schema extension](https://datatracker.ietf.org/doc/html/rfc7643#section-4.3) en een [custom extension schema](https://datatracker.ietf.org/doc/html/rfc7643#section-3.3).

### Gemeenschappelijke group-objectattributen

[RFC-7643: Common attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-3.1)

De volgende gemeenschappelijke attributen worden door Zivver geleverd en kunnen niet worden aangepast.

- **externalId**: primair e-mailadres (verplicht)

_\_Zivver identificeert een groepsaccount aan de hand van het primaire e-mailadres. Omdat Groups niet altijd een `userName` hebben, moet `externalId` het primaire e-mailadres van het gedeelde account bevatten. Dit verschilt van het User-object, waarin het primaire e-mailadres in `userName` staat._

Zivver levert de volgende extra gemeenschappelijke attributen, dus het is niet nodig deze aan te maken.

- **id**: unieke identifier (geleverd)

_\_De `id` wordt door Zivver verstrekt en kan niet worden aangepast. Wordt gebruikt voor SCIM-bewerkingen._

- **meta.resourceType**: Group (geleverd)

- **meta.created**: aanmaakdatum account (geleverd)

_\_De aanmaakdatum wordt door Zivver verstrekt en kan niet worden aangepast._

- **meta.location**: `/scim/v2/Groups/{id}` (geleverd)

### Enkelvoudige group-objectattributen

[RFC-7643: Singular attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-4.2)

Verplicht attribuut voor group-objecten:

- **displayName**: weergavenaam voor eindgebruikers (verplicht)

_\_Zivver gebruikt deze naam om aan eindgebruikers te tonen hoe het account heet._

### Multi-value group-objectattributen

[RFC-7643: Multi-value attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.2)

Verplicht attribuut voor group-objecten:

- **members**: gebruikers met volledige toegang tot het account (verplicht)

_\_Bevat een lijst van Zivver user `{id}`-waarden die toegang hebben. Deze accounts kunnen berichten verzenden en ontvangen namens het functionele account._

Info

**Belangrijke informatie over members**

Gebruik de unieke `{id}` van gebruikers, niet e-mailadressen. Zie [Voorbeeld volledige group-representatie](https://docs.zivver.com/nl/admin/integrations/scim-v2.html#example-full-group-representation).

### Enterprise User Schema Extension

[RFC-7643: Enterprise user schema extension](https://datatracker.ietf.org/doc/html/rfc7643#section-4.3)

Gebruik dit attribuut alleen als je organisatie met [Organisatie-Eenheden](https://docs.zivver.com/nl/admin/webapp/organizational-units.html) werkt.

**urn:ietf:params:scim:schemas:extension:enterprise:2.0:User**

- **division**: Organisatie-Eenheid van het functionele account (optioneel)

_\_Zivver gebruikt dit attribuut om het account aan de juiste Organisatie-Eenheid te koppelen._

Info

**Hoe weet ik of mijn organisatie Organisatie-Eenheden gebruikt?**

### Zivver’s Custom Extension Schema

[RFC-7643: Custom schema extension](https://datatracker.ietf.org/doc/html/rfc7643#section-3.3)

**urn:ietf:params:scim:schemas:zivver:0.1:Group**

- **aliases**: lijst met e-mailaliassen (optioneel)

_\_Gebruikers van het functionele account kunnen berichten ontvangen op deze aliassen._

### Voorbeeld minimale group-representatie

Het volgende is een niet-normatief voorbeeld van de minimale SCIM Group-representatie in JSON-formaat.

```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "meta": {
    "resourceType": "Group",
    "created": "2010-01-23T04:56:22Z",
    "location": "/scim/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a"
  },
  "displayName": "Department A",
  "externalId": "department@example.com",
  "id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
  "members": [
    {"value": "2819c223-7f76-453a-919d-413861904646"},
    {"value": "5737d357-5a46-267n-111e-6783178326"}
  ]
}
```

### Voorbeeld van volledige group-representatie

Het volgende is een niet-normatief voorbeeld van een volledig ingevulde SCIM Group-representatie in JSON-formaat.

```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "urn:ietf:params:scim:schemas:zivver:0.1:Group"],
  "meta": {
    "resourceType": "Group",
    "created": "2010-01-23T04:56:22Z",
    "location": "/scim/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a"
  },
  "displayName": "Department A",
  "externalId": "department@example.com",
  "id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
  "members": [
    {"value": "2819c223-7f76-453a-919d-413861904646"},
    {"value": "5737d357-5a46-267n-111e-6783178326"}
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "division": "Development"
  },
  "urn:ietf:params:scim:schemas:zivver:0.1:Group": {
    "aliases": ["development@example.com"]
  }
}
```

Laatst bijgewerkt op 2026-06-18