Introduction

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.

Account management in Zivver

Zivver accounts can either 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. Zivver advises organizations with more than 100 employees to automate account management. Zivver recommends the Zivver Synctool for automated account management.

Zivver distinguishes between normal and functional account types. Each account type is managed differently and both account types will be discussed in this manual.

How to connect to the Zivver SCIM v2 endpoint

The connection is authenticated by using a Bearer Token. For this purpose a Zivver admin can create an API key from the Zivver admin panel to authenticate the connection. A SCIM client should send the in Zivver generated API key as a token in the Authorization header, as stated 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}

Supported SCIM operations

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

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

How to manage normal Zivver accounts

You can log on to a Normal Zivver account either via a Zivver password or via Single Sign-On (SSO). Zivver uses the SCIM resource type “Users” to manage normal 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 below 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 on its primary email address.

• name.formatted: display name (mandatory)
  Zivver uses the display name to show recipients who sent a Zivver message. Zivver advises to populate this field with a first name and the surname.

• nickName: nickname (optional)
  Zivver uses this name in the salutation when sending notification messages.

• active: user account is active or not active. That means suspended (mandatory).
  Zivver uses this information to suspend normal Zivver accounts. Zivver recommends to suspend Zivver accounts when the associated employee leaves service. A suspended user will be 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 set up as a 2FA (optional)
  Zivver uses the first phone number in the list to set up a 2FA to protect the normal Zivver account. Make sure that this first phone number is a phone number which 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: to which Organizational Unit does the normal account belong in Zivver (optional).
  Zivver uses the information about the division to map the normal Zivver account to the right Organization Unit within the Zivver organization.

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 Single Sign-On (SSO) is not used [mandatory unless SSO is used]
  Zivver uses the password to generate the encryption keys to protect the account and any sent or received messages. This attribute should contain the user’s Zivver password to log in to the account for the first time. After the first login users are prompted to create their own passwords.

• SsoAccountKey: the user’s ZivverAccountKey when using Single Sign-On (SSO) [mandatory when using SSO]
  Zivver uses the ZivverAccountKey to generate the encryption keys that are used to protect the account and any sent or received messages.
  

  Important information about the ZivverAccountKey
  Because the ZivverAccountKey will be used to generate the encryption keys that are used to protect the account and any sent/received messages, it is important that the ZivverAccountKey is long, unique and random. Preferably, the ZivverAccountKey is generated by your organization and is not used by other integrations or systems. If it is not possible to generate this number yourself, using the Active Directory (AD) attribute “objectGUID” is an alternative. However, this number is often used in other integrations, and is therefore a security risk. The attribute “ObjectSID” or other AD attributes should not be used, because these values ​​are easy to guess.

• aliases: a list of email aliases (optional)
  Zivver uses email aliases so that users can receive Zivver messages at their alias email address. This attribute should contain a list of email aliases at which the user should be able to receive Zivver messages.

• delegates: a list of email addresses that have full access to this normal account (optional)
  Zivver uses email delegates so that users can read and send Zivver messages on behalf of other users. This attribute should contain a list of email addresses of normal Zivver accounts that have delegated access to this normal Zivver account.
  

  Important information about the Delegates
  delegates is a list of email addresses, not a list of user {id}’s.

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 the fully populated SCIM 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 normal account has delegated access to a functional account, then you are automatically logged in to a functional Zivver 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 below common group object attributes are provided by Zivver and cannot be changed.

• externalId: primary email address (mandatory)
  Zivver identifies an account on its primary email address. As Groups might not always have a userName, the externalId must contain the primary email address of the shared account. This is different for the User Object in which the primary email address is used in the userName attribute.

Zivver provides the following common group object attributes. Therefore it’s not needed to create these attributes.

• 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: Group (provided)

• meta.created: account creation date (provided)
  The created 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 display to end-users what the name of this account is.

Multi-value group object attributes

RFC-7643: Multi-value attributes

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

• members: users that have full access to the group account (mandatory)
  Zivver uses this attribute to delegate access to functional accounts. This attribute should contain a list id’s of normal Zivver accounts that have access to this functional account. With delegated access, normal Zivver accounts can receive messages and send on behalf of this functional Zivver account.
  

  Important information about the members
  Make sure to use the users’ unique identifier {id} to list the members of groups, not the email addresses. 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 this attribute when your organization uses Organizational Units in Zivver.

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

• division: to which Organizational Unit does the normal account belong in Zivver (optional).
  Zivver uses the information about the division to map the normal Zivver account to the right Organization Unit within the Zivver organization.

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

This schema contains the following attributes:

• aliases: a list of email aliases (optional)
  Zivver uses email aliases so that functional accounts can receive Zivver messages at their alias email address. This attribute should contain a list of email aliases at which the functional account should be able to receive Zivver messages.

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 the fully populated SCIM Group 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"]
  }
}