# Synchronize accounts to Zivver via SCIM 2.0

## Introduction

This article explains how to directly communicate with the Zivver SCIM V2 API endpoint. You can use this information if your organization wants to automatically manage Zivver accounts by building its own SCIM connection.

Info

Do not use the Zivver SCIM V2 API endpoint to connect to existing SCIM endpoints such as Entra ID or Google Workspaces. This limitation exists because automated account provisioning from one of these systems requires the [Zivver Synctool](https://docs.zivver.com/en/admin/synctool-v2/synctool-manual.html).

## Account management in Zivver

Zivver accounts can be managed manually via the [Zivver admin panel](https://app.zivver.com/organization/accounts), or automatically by using the Zivver System for Cross-domain Identity Management (SCIM) API. Zivver follows the SCIM 2.0 specifications. For organizations with more than 100 employees, Zivver advises automating account management. Zivver recommends the [Zivver Synctool](https://docs.zivver.com/en/admin/synctool-v2/synctool-manual.html) for automated account provisioning.

Zivver distinguishes between normal and functional account types. Each account type is managed differently, and both account types are explained in this manual.

| **Account Type** | **Description** |
| --- | --- |
| Normal | Personal account that a user can log in to. |
| Functional | Shared account that you cannot log in to directly. With [Delegated access](https://docs.zivver.com/en/admin/webapp/references/account-delegation.html), a user can send and receive Zivver messages from a functional account. |

## How to connect to the Zivver SCIM v2 endpoint

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

The connection is authenticated by using a [Bearer Token](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1). A Zivver admin can create an API key from the [Zivver admin panel](https://app.zivver.com/organization/api-keys) to authenticate the connection. A SCIM client must send the API key generated in Zivver as a token in the **Authorization** header, as specified in [RFC6750 section 2.1](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1):

> Clients [SHOULD](https://datatracker.ietf.org/doc/html/rfc2119) make authenticated requests with a bearer token using the “Authorization” request header field with the “Bearer” HTTP authorization scheme.

For example:

> Authorization: Bearer {base64 encoded Zivver API key}

Info

**Encoding the bearer token in base64**

The HTTP specifications require the client to encode the bearer token in base64. Existing tools or libraries typically perform this automatically.

## Supported SCIM operations

The following SCIM operations are supported by the Zivver SCIM v2 endpoint:

- 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}`

Warning

**Delete: DELETE**

Deleting Zivver accounts is irreversible. Data lost from deleting an account cannot be retrieved. Zivver recommends setting the value of the `active` attribute to `false` (suspend) instead of deleting the account.

Info

**Update: PATCH**

Support for this operation is limited to Microsoft Entra ID. For other clients, it is recommended to use the PUT operation instead.

## How to manage Zivver user accounts

You can log in to a Zivver user account either with a Zivver password or via [Single Sign-On (SSO)](https://docs.zivver.com/en/admin/sso/sso-intro.html). Zivver uses the SCIM resource type **Users** to manage Zivver user accounts, based on the following schema:

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

The user object must contain [common attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-3.1) and [singular attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.1). Additionally, Zivver uses [multi-value attributes](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.2), the [enterprise user schema extension](https://datatracker.ietf.org/doc/html/rfc7643#section-4.3), and a [custom extension schema](https://datatracker.ietf.org/doc/html/rfc7643#section-3.3).

### Common user object attributes

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

The following common user object attributes are provided by Zivver and cannot be changed.

- **id**: unique identifier returned by Zivver (provided)

_The id is provided by Zivver and cannot be changed. The `{id}` is used for SCIM operations._

- **meta.resourceType**: user (provided)

- **meta.created**: account creation date (provided)

_The created date is provided by Zivver and cannot be changed._

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

### Singular user object attributes

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

Zivver uses the following mandatory and optional singular attributes for user objects.

- **userName**: primary email address (mandatory)

_Zivver identifies an account by its primary email address._

- **name.formatted**: display name (mandatory)

_Zivver uses the display name to show recipients who sent a Zivver message. Zivver recommends populating this field with a first name and surname._

- **nickName**: nickname (optional)

_Zivver uses this value in the salutation when sending notification messages._

- **active**: whether the user account is active or inactive (suspended) (mandatory)

_Zivver uses this information to suspend user accounts. Zivver recommends suspending an account when the associated employee leaves the organization. A suspended user is activated again when the active state equals `true`._

### Multi-value user object attributes

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

Zivver uses the following optional multi-value attributes for user objects.

- **phoneNumbers**: the first phone number in the list is used for 2FA (optional)

_Zivver uses the first phone number in the list to set up 2FA. Ensure this phone number can receive text messages._

### Enterprise user schema Extension

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

Zivver uses the following additional attribute from the enterprise user schema extension. Only use this attribute when your organization uses [Organizational Units](https://docs.zivver.com/en/admin/webapp/organizational-units.html) in Zivver.

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

- **division**: the Organizational Unit to which the user account belongs (optional)

_Zivver uses the division attribute to map the user account to the correct Organizational Unit._

### Zivver’s custom Extension schema

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

Zivver extends the above attributes with the following custom schema:

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

This schema contains the following attributes:

- **password**: the user’s Zivver password when SSO is not used (mandatory unless SSO is used)

_Zivver uses the password to generate encryption keys that protect the account and all messages. This attribute should include the user’s Zivver password **for the first login**. After the first login, users must create their own password._

- **SsoAccountKey**: the user’s ZivverAccountKey when using SSO (mandatory when using SSO)

_Zivver uses the ZivverAccountKey to generate the encryption keys that protect the account and all messages._

- **aliases**: list of email aliases (optional)

_Zivver uses email aliases so users can receive Zivver messages at these alternate addresses._

- **delegates**: list of email addresses that have full access to this user account (optional)

_Zivver uses delegates so users can read and send messages on behalf of others._

### Example minimal user representation

The following is a non-normative example of the minimal required SCIM representation in JSON format.

```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"
}
```

### Example full user representation

The following is a non-normative example of a fully populated SCIM user representation in JSON format.

```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"
}
```

## How to manage functional Zivver accounts

Functional Zivver accounts are shared accounts. If your Zivver user account has delegated access to a functional account, you are automatically logged in to that functional account. In Zivver, the SCIM resource type **Groups** is used, based on the following schema:

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

The group object must contain a [common attribute](https://datatracker.ietf.org/doc/html/rfc7643#section-3.1), a [singular attribute](https://datatracker.ietf.org/doc/html/rfc7643#section-4.2), and a [multi-value attribute](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.2). Additionally, Zivver uses the [enterprise user schema extension](https://datatracker.ietf.org/doc/html/rfc7643#section-4.3) and a [custom extension schema](https://datatracker.ietf.org/doc/html/rfc7643#section-3.3).

### Common group object attributes

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

The following common group object attributes are provided by Zivver and cannot be changed.

- **externalId**: primary email address (mandatory)

_Zivver identifies a group account by its primary email address. As Groups might not have a `userName`, the `externalId` must contain the primary email of the shared account. This differs from the User object, where the primary email is in the `userName` attribute._

Zivver provides the following additional common group object attributes. You do not need to create them.

- **id**: unique identifier returned by Zivver (provided)

_The `id` is provided by Zivver and cannot be changed. It is used for SCIM operations._

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

- **meta.created**: account creation date (provided)

_The creation date is provided by Zivver and cannot be changed._

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

### Singular group object attributes

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

Zivver uses the following mandatory singular attribute for group objects.

- **displayName**: the display name to end-users (mandatory)

_Zivver uses this name to show end-users the account name._

### Multi-value group object attributes

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

Zivver uses the following mandatory multi-value attribute for group objects.

- **members**: users with full access to the group account (mandatory)

_This attribute delegates access to functional accounts. It should contain a list of Zivver user `{id}` values that have access. Delegated users can send and receive messages on behalf of the functional account._

### Example minimal group representation

The following is a non-normative example of the minimal required SCIM Group representation in JSON format.

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

### Example full group representation

The following is a non-normative example of a fully populated SCIM Group user representation in JSON format.

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

Updated on 2026-06-18