This article outlines how organizations can use Udemy’s System for Cross-domain Identity Management (SCIM) API to add or remove user licenses.
SCIM is supported by a number of Identity Providers such as Okta and OneLogin. You can also utilize the Udemy Business SCIM API for other IdPs or home-grown tools.
Note: SCIM API tokens for Udemy Business last for approximately two years. Admins will be sent a notification informing them of:
- 30 days before the token expiry
- After the token expiry
License usage
In the Identity Provider, typically licenses are assigned at a group level or, in some cases, at an individual level. When the licenseType attribute is included in requests, the type of license will be specified for the users in question.
- The attribute may be included when creating users, and the users will claim the indicated licenses once they activate their Udemy Business account.
- The attribute may be included for an existing user and can either grant or remove an existing license.
- If insufficient licenses of a required type are available on the account, Udemy Business will send an error message to the IdP, and changes will not be made.
Restrictions on removing licenses:
A user must have a license type. To free up all licenses from a user, the user will need to be deactivated in your organization’s account. If Udemy Business receives a blank licenseType attribute, the system will ignore it.
Downgrading from a “Pro” to “Enterprise” license is not currently supported for inactive users, i.e., users that were provisioned with both licenses but who have not logged in yet.
Providing the required licenseType attribute
The licenseTypes attribute that must be included in your organization’s Identity Provider is:
urn:ietf:params:scim:schemas:extension:udemy:2.0:User.
This attribute should be provided as a list of strings, with each string representing a license name (see the section below regarding license types for more information).
Providing the accepted values and corresponding license types
In order to manage a user’s license type an accepted value will need to be entered. The input values in the table below will be validated against the supported license types for Udemy Business. The license name value is not case sensitive.
| License name | Type |
Examples of accepted values |
| Enterprise | Plan license |
Enterprise, eNtErpRisE, enTERprise,etc. |
|
Pro |
Additional license |
Pro, pRo, PRo,etc. |
Note: If an unaccepted value is provided, an error notification will occur.
How to include licenseTypes when creating users
The following is an example of what would be entered into your Identity Provider to include licenseTypes when creating users:
POST /scim/v2/Users HTTP/1.1
Host: myorganization.udemy.com
Accept: application/scim+json
Authorization: Bearer <enter your Bearer token here>
Content-Type: application/scim+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:extension:udemy:2.0:User"
],
"userName": "john.doe@udemy.com",
"externalId": "someexternalidtest12312",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"emails": [
{
"primary": true,
"type": "work",
"value": "john.doe@udemy.com"
}
],
"active": true,
"urn:ietf:params:scim:schemas:extension:udemy:2.0:User": {
"licenseTypes": ["Enterprise", "Pro"]
}
}How to replace the attributes of existing users and include licenseTypes
The following is an example of what would be entered to replace the attributes of existing users and include licenseTypes:
PUT /scim/v2/Users/<scim-user-uuid> HTTP/1.1
Host: myorganization.udemy.com
Accept: application/scim+json
Authorization: Bearer <enter your Bearer token here>
Content-Type: application/scim+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:extension:udemy:2.0:User"
],
"userName": "john.doe@udemy.com",
"externalId": "someexternalidtest12312",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"emails": [
{
"primary": true,
"type": "work",
"value": "john.doe@udemy.com"
}
],
"active": true,
"urn:ietf:params:scim:schemas:extension:udemy:2.0:User": {
"licenseTypes": ["Enterprise", "Pro"]
}
}
How to set only the licenseTypes field of an existing user
In order to set only the licenseTypes field on an existing user, there are two options for PATCH requests use:
"op": "add"
To add the add-on license (i.e. “Pro”) to already existing ones, use:
"op": "replace"
to overwrite existing values.
Note:
With the add operation, a Udemy Business Pro license can be added to existing licenses, which are either Enterprise or Enterprise+Pro. For users who already have Enterprise licenses, the Pro license will be added. For users who already have Enterprise+Pro licenses, no additional license will be added.
Here is an example of what would be entered to set only the licenseTypes field on an existing user:
PATCH /scim/v2/Users/<scim-user-uuid> HTTP/1.1
Host: myorganization.udemy.com
Accept: application/scim+json
Authorization: Bearer <enter your Bearer token here>
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp",
"urn:ietf:params:scim:schemas:extension:udemy:2.0:User",
],
"Operations": [
{
"op": "add",
"urn:ietf:params:scim:schemas:extension:udemy:2.0:User": {
"licenseTypes": ["Pro"]
}
}
]
}WHow to overwrite the entire set of current licenses for a user
With the replace operation, the whole set of current licenses for a user can be overwritten. To do so, the following must be entered.
PATCH /scim/v2/Users/<scim-user-uuid> HTTP/1.1
Host: myorganization.udemy.com
Accept: application/scim+json
Authorization: Bearer <enter your Bearer token here>
Content-Type: application/scim+json
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp",
"urn:ietf:params:scim:schemas:extension:udemy:2.0:User",
],
"Operations": [
{
"op": "replace",
"urn:ietf:params:scim:schemas:extension:udemy:2.0:User": {
"licenseTypes": ["Enterprise", "Pro"]
}
}
]
}