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 is a limitation. For automated account provisioning from one of these systems, we recommend the Zivver Synctool.

Account management in Zivver

Zivver accounts can be managed manually via the Zivver admin panel, 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 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.

How to connect to the Zivver SCIM v2 endpoint

The connection is authenticated by using a Bearer Token. A Zivver admin can create an API key from the Zivver admin panel 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:

Clients SHOULD 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). 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 and singular attributes. Additionally, Zivver uses multi-value attributes, the enterprise user schema extension, and a custom extension schema.

Common user object attributes

RFC-7643: Common Attributes

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

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

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

Zivver uses the following additional attribute from the enterprise user schema extension. Only use this attribute when your organization uses Organizational Units 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.

Info

How do I find out if my organization uses organizational units in Zivver?
If your organization uses organizational units in Zivver, you should have access to the Organizational Units tab. If you do not have access, your organization may not use them, or you may not have administrator rights.

Zivver’s Custom Extension Schema

RFC-7643: Custom schema extension

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.
  

  Info

  Important information about the ZivverAccountKey
  Because the ZivverAccountKey is used to generate encryption keys, it must be long, unique, and random. Preferably, your organization generates this key and does not reuse it across systems. If generating your own key is not possible, using the Active Directory (AD) attribute objectGUID is an alternative. However, because this value is often reused in other integrations, it introduces a security risk. The objectSID attribute or similar AD attributes must not be used, as these are predictable.

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

  Info

  Important information about delegates
  delegates is a list of email addresses, not user {id} values.

Example minimal user representation

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

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

{
  "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, a singular attribute, and a multi-value attribute. Additionally, Zivver uses the enterprise user schema extension and a custom extension schema.

Common group object attributes

RFC-7643: Common attributes

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

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

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

  Important information about members
  Use users’ unique {id} values, not email addresses, to list group members. See Example full group representation.

Enterprise User Schema Extension

RFC-7643: Enterprise user schema extension

Zivver uses the following additional attribute from the enterprise user schema extension. Only use it if your organization uses Organizational Units in Zivver.

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

• division: the Organizational Unit of the functional account (optional)
  Zivver uses this to map the functional account to the correct Organizational Unit.

Info

How do I find out if my organization uses organizational units in Zivver?
If your organization uses them, you should have access to the Organizational Units tab. No access means either your organization doesn’t use them or you lack administrator rights.

Zivver’s Custom Extension Schema

RFC-7643: Custom schema extension

Zivver extends the above attributes with the following custom schema:

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

• aliases: list of email aliases (optional)
  Zivver uses aliases so functional accounts can receive messages at these addresses.

Example minimal group representation

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

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

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