View on GitHub

TeamViewer SCIM API Documentation

Technical description of the "System for Cross-domain Identity Management" API as implemented by TeamViewer

Introduction

The System for Cross-domain Identity Management (SCIM) defines an API that can be used by Identity Providers to automatically provision, update and deprovision users. TeamViewer implements this API to a certain extent and therefore allows automatic creation, updates and deactivation of users in a TeamViewer company.

This article describes the TeamViewer SCIM API and uses the terms and numbers defined in the “TeamViewer API Documentation” (chapter 2 - “Introduction”).

Authorization

The TeamViewer SCIM API uses OAuth 2.0 based authorization, as described in the “TeamViewer API Documentation”.

The access token can be created in the TeamViewer Management Console and needs to be given in the HTTP Authorization header, sent by the Identity Provider. Please see the respective documentation of the IdP on how to configure the authorization token.

The access token requires to have the following scopes:

This corresponds to the following entries in the TeamViewer Management Console “Script Token” dialog:

API Token Attributes

SCIM API User Resource

User Attributes

The following table summarizes the TeamViewer User properties and how they are mapped to the respective SCIM attributes.

TeamViewer User Property SCIM Attribute(s) Description
id id The user ID that is needed to uniquely identify the TeamViewer user.
This ID needs to start with a "u".
name displayName
name.formatted
name.givenName
name.familyName
The name of the TeamViewer user.
The "displayName" attribute holds the actual name of the user when returned by the API. It also has precedence over any other name attribute when setting the user name.
The "name.formatted" attribute holds the same value as the "displayName" attribute when returned by the API. On input, it is used if the "displayName" is not given.
The "name.givenName" attribute holds the first part of the TeamViewer user name when split by space - the "name.familyName" holds the rest. If the name does not contain spaces, both values will be null.
On input, these values are only considered for the user name if neither the "displayName" or "name.formatted" attributes are set. The name is then built by separating "givenName" and "familyName" with a space character.
email userName
emails[0].value 		The email address of the TeamViewer user.
When returned by the API, the "userName" attribute holds the email address of the respective user.
TeamViewer supports only a single email address per user.
active active The state of the user account. True, if the account is enabled, false otherwise.
password password The password for a newly created TeamViewer user.
This attribute will never be included in an API response and is only used for creating users.
language preferredLanguage The language code for a newly created TeamViewer user. This will be used for the welcome email.
This attribute will not be included in API responses and is only used for creating users.

Get a list of users

GET /scim/v2/Users

Lists all users in a TeamViewer company. The list can optionally be filtered and paginated.

Parameters

Example

Request

GET /scim/v2/Users?filter=userName ew "example.test"

Response - 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 3,
    "startIndex": 0,
    "itemsPerPage": 3,
    "Resources": [
        {
            "id": "u1234567",
            "name": {
                "givenName": "John",
                "familyName": "Doe",
                "formatted": "John Doe"
            },
            "displayName": "John Doe",
            "emails": [
                {
                    "primary": true,
                    "value": "johndoe@example.test"
                }
            ],
            "userName": "johndoe@example.test",
            "active": true
        },
        { … },
        { … }
    ]
}

Get a single user

GET /scim/v2/Users/{id}

Returns the information for a single user. The “id” placeholder must be replaced by the user’s ID as returned by the list-operation.

Parameters

Example

Request

GET /scim/v2/Users/u1234567

Response - 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "u1234567",
    "name": {
        "givenName": "John",
        "familyName": "Doe",
        "formatted": "John Doe"
    },
    "displayName": "John Doe",
    "emails": [
        {
            "primary": true,
            "value": "johndoe@example.test"
        }
    ],
    "userName": "johndoe@example.test",
    "active": true
}

Create a new user

POST /scim/v2/Users

Creates a new user for the TeamViewer company. The new user is returned as response to this operation. Optionally, users can be created to be enabled for Single Sign-On and will therefore not require a TeamViewer account password.

Parameters

Given as JSON formatted payload in the request body.

Example #1 - Normal User

Request

POST /scim/v2/Users
Content-Type: application/scim+json

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "jane.doe@example.test",
    "displayName": "Jane Doe",
    "emails": [
        {
            "value": "jane.doe@example.test",
            "primary": true
        }
    ],
    "name": {
        "givenName": "Jane",
        "familyName": "Doe",
        "formatted": "Jane Doe"
    },
    "password": "secret1!",
    "preferredLanguage": "de_DE"
}

Response - 201 Created

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "u1234567",
    "name": {
        "givenName": "Jane",
        "familyName": "Doe",
        "formatted": "Jane Doe"
    },
    "displayName": "Jane Doe",
    "emails": [
        {
            "primary": true,
            "value": "jane.doe@example.test"
        }
    ],
    "userName": "jane.doe@example.test",
    "active": true
}

Example #2 - Single Sign-On User

Request

POST /scim/v2/Users
Content-Type: application/scim+json

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:teamviewer:1.0:SsoUser"
    ],
    "userName": "jane.doe@example.test",
    "displayName": "Jane Doe",
    "emails": [
        {
            "value": "jane.doe@example.test",
            "primary": true
        }
    ],
    "name": {
        "givenName": "Jane",
        "familyName": "Doe",
        "formatted": "Jane Doe"
    },
    "preferredLanguage": "de_DE",
    "urn:ietf:params:scim:schemas:extension:teamviewer:1.0:SsoUser": {
        "ssoCustomerId": "a1b2bc4d5e6f7"
    }
}

The response is similar to the one given in the first example for this endpoint.

Update an existing user

PUT /scim/v2/Users/{id}

Changes information for the selected user. The “id” placeholder must be replaced by the user’s ID as returned by the list-operation. The “PUT” operation intends to replace an existing resource. Therefore the request should include the complete (updated) user information. This includes attributes that do not change. Responds with the updated User resource.

Parameters

Given as JSON formatted payload in the request body:

Example

Request

PUT /scim/v2/Users/u1234567
Content-Type: application/scim+json

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "jane.doe@example.test",
    "displayName": "Jane Doe (Updated Name)",
    "emails": [
        {
            "value": "jane.doe@example.test",
            "primary": true
        }
    ],
    "name": {
        "givenName": "Jane",
        "familyName": "Doe (Updated Name)",
        "formatted": "Jane Doe (Updated Name)"
    },
    "active": true
}

Response - 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "u1234567",
    "name": {
        "givenName": "Jane",
        "familyName": "Doe (Updated Name)",
        "formatted": "Jane Doe (Updated Name)"
    },
    "displayName": "Jane Doe (Updated Name)",
    "emails": [
        {
            "primary": true,
            "value": "jane.doe@example.test"
        }
    ],
    "userName": "jane.doe@example.test",
    "active": true
}

Update properties of an existing user

PATCH /scim/v2/Users/{id}

Changes information for the selected user. The “id” placeholder must be replaced by the user’s ID as returned by the list-operation. The “PATCH” operation can be used to change single properties of a user. Only the parts that need to be changed are needed in the request body. Responds with the updated User resource.

Parameters

Given as JSON formatted payload in the request body:

Example

Request

PATCH /scim/v2/Users/u1234567
Content-Type: application/scim+json

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "replace",
            "value": {
                "active": false
            }
        },
        {
            "op": "replace",
            "path": "displayName",
            "value": "Jane Doe Updated"
        }
    ]
}

Response - 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "u1234567",
    "name": {
        "givenName": "Jane",
        "familyName": "Doe Updated",
        "formatted": "Jane Doe Updated"
    },
    "displayName": "Jane Doe Updated",
    "emails": [
        {
            "primary": true,
            "value": "jane.doe@example.test"
        }
    ],
    "userName": "jane.doe@example.test",
    "active": false
}