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").
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:
Users.CreateUsers(orUsers.CreateAdministrators)Users.ReadUsers.ModifyUsersUsers.ModifyAdministrators(optional)
This corresponds to the following entries in the TeamViewer Management Console "Script Token" dialog:
- UserManagement: View, create and edit users
- UserManagement: View, create and edit users and admins (optional)
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. |
|
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 /scim/v2/Users
Lists all users in a TeamViewer company. The list can optionally be filtered and paginated.
-
filter (optional)
Enables filtering of the user list.
Example:filter=userName eq "[email protected]"-
Supported filter operators (matches case-sensitive):
eq: Attribute must match exactly.ne: Attribute must not match.co: Attribute must contain given value.sw: Attribute must start with given value.ew: Attribute must end with given value.
-
Supported attributes to filter on:
userName(corresponds to email address)emails.valuenamedisplayName
-
-
startIndex (optional)
Used for pagination. This is the (1-based) index to start returning values for. It defaults to 1 if not present.
-
count (optional)
The maximum number of items to include in the result set.
If not given, all items will be returned, beginning from the optionally given "startIndex".
GET /scim/v2/Users?filter=userName ew "example.test"
{
"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": "[email protected]"
}
],
"userName": "[email protected]",
"active": true
},
{ … },
{ … }
]
}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.
-
id (path)
The user's ID as returned by the list-operation.
GET /scim/v2/Users/u1234567
{
"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": "[email protected]"
}
],
"userName": "[email protected]",
"active": true
}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.
Given as JSON formatted payload in the request body.
-
schemas
Must include the "urn:ietf:params:scim:schemas:core:2.0:User" schema.
-
userName
The email address for the new user. Will be used for login.
This attribute has precedence over the "emails" parameter. -
displayName
The name of the new user.
This attribute has precedence over the "name" parameter. -
emails
List of email addresses of the user. Values will only be evaluated if the email address is not given in the "userName" attribute. If multiple values are present, the first entry marked as primary email address is taken. If no primary email address is given, the first entry in the list is considered as the email address of the new user.
-
name
Parts of the name of the new user.
The following order applies in building the name for the new user:- If given, use the "displayName"
- Else, if given use the "name.formatted"
- Otherwise build the name by separating "name.givenName" and "name.familyName" by a space-character.
-
password (optional)
Predefined password for the user. Will be used for login.
-
preferredLanguage (optional)
Language for the new user. Will be used for the welcome email. Defaults to "en".
-
ssoCustomerId (optional)
The customer identifier that is needed for Single Sign-On. If this parameter is specified, newly created users are SSO-enabled and do not need a TeamViewer account password.
This parameter is part of the SCIM extension schemaurn:ietf:params:scim:schemas:extension:teamviewer:1.0:SsoUser
POST /scim/v2/Users
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "[email protected]",
"displayName": "Jane Doe",
"emails": [
{
"value": "[email protected]",
"primary": true
}
],
"name": {
"givenName": "Jane",
"familyName": "Doe",
"formatted": "Jane Doe"
},
"password": "secret1!",
"preferredLanguage": "de_DE"
}
{
"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": "[email protected]"
}
],
"userName": "[email protected]",
"active": true
}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": "[email protected]",
"displayName": "Jane Doe",
"emails": [
{
"value": "[email protected]",
"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.
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.
-
id (path)
The user's ID as returned by the list-operation.
Given as JSON formatted payload in the request body:
-
schemas
Must include the "urn:ietf:params:scim:schemas:core:2.0:User" schema.
-
userName
The email address of the user.
This attribute has precedence over the "emails" parameter.
Changes the email address of the user if different than the current email address. A verification Email will be sent to the new address. -
displayName
The name of the new user.
This attribute has precedence over the "name" parameter.
Changes the name of the user if different than the current name. -
emails
List of email addresses of the user. Values will only be evaluated if the email address is not given in the "userName" attribute. If multiple values are present, the first entry marked as primary email address is taken. If no primary email address is given, the first entry in the list is considered as the email address of the new user.
-
name
Parts of the name of the user.
The following order applies in building the name for the new user:- If given, use the "displayName"
- Else, if given use the "name.formatted"
- Otherwise build the name by separating "name.givenName" and "name.familyName" by a space-character.
-
active
The state of the user account. True, if the account is enabled, false otherwise.
Can be used to activate/deactivate the user account.
PUT /scim/v2/Users/u1234567
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "[email protected]",
"displayName": "Jane Doe (Updated Name)",
"emails": [
{
"value": "[email protected]",
"primary": true
}
],
"name": {
"givenName": "Jane",
"familyName": "Doe (Updated Name)",
"formatted": "Jane Doe (Updated Name)"
},
"active": true
}
{
"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": "[email protected]"
}
],
"userName": "[email protected]",
"active": true
}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.
-
id (path)
The user's ID as returned by the list-operation.
Given as JSON formatted payload in the request body:
-
schemas
Must include the "urn:ietf:params:scim:api:messages:2.0:PatchOp" schema.
-
Operations
List of operations to apply to the selected user.
-
op
Type of change operation to perform. The only supported operation type is "replace".
-
path (optional)
Optional path of the attribute to change. Child attributes of need to be separated by dot (.) from their parent attribute (e.g. "name.givenName").
-
value
Parts of the user to change.
If the "path" attribute is omitted, this needs to be a partial User object. Otherwise the value of the respective attribute, addressed by "path".
Changing the following attributes is supported:userNamedisplayNameemails.valuename.formattedname.givenNamename.familyNameactive
-
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"
}
]
}
{
"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": "[email protected]"
}
],
"userName": "[email protected]",
"active": false
}