System for Cross-domain Identity Management (SCIM) Provisioning

  • Configure SCIM Provisioning With Entra ID (Azure AD)

    Once Single Sign-on (SSO) is set up you can configure Udemy for Cross-domain Identity Management (SCIM 2.0) provisioning in Entra ID (formerly Azure AD) with Udemy Business. This will allow you to provision, deprovision, create groups, manage group membership and change user profile details like name and email address in Entra ID, which automatically updates Udemy Business. You will no longer need to update both Entra ID and Udemy Business separately with these actions as it will all be synced from Entra ID.

    Please note: Entra ID is formerly known as Azure AD.

    To enable SCIM Provisioning for your Udemy Business account, first go to your Udemy Business account and access Manage > Settings > Provisioning (SCIM).

    Click Start Setup and follow the instructions to enable SCIM and generate the Secret Token (Bearer token) which you then need to put into Entra ID.

    Please note:

    • SSO must be enabled prior to activating SCIM
    • Single sign-on and provisioning are available to Udemy Business Enterprise Plan customers.
    • Users provisioned through Entra ID will not take up a license until they log into the Udemy Business application for the first time. 
    • SCIM provisioning changes can only be synced from Entra ID to Udemy Business, not the other way round. 
    • Users and Groups managed by SCIM in Entra ID cannot be changed within the Udemy Business app - SCIM is the single source of truth for user and group data.
    • You can still create groups manually in Udemy Business if you have users that you don’t need or want to push from Entra ID, eg. contractors or temporary staff.

    Configure SCIM Provisioning with Entra ID

    1. To enable SCIM Provisioning for Udemy Business, first go to your Udemy Business account and access Manage > Settings > Provisioning (SCIM).

    2. Click Start Setup, choose your Identity Provider and follow the instructions to generate the Secret Token (Bearer token) which you then need to input into Entra ID.

    1a.png

    3. Next, access your Entra ID account and go to your Udemy Business SSO app and follow the steps below to get set up. You can also refer to Microsoft’s own configuration guide for SCIM Provisioning with Entra ID for further guidance.

    Go to the Provisioning tab in your Azure portal.   

    (Note: udemyazure is a test name we used in the screenshots below for the purpose of illustrating how to configure SCIM; you should locate the app that was named by your team when configuring within your own instance) 

    1b.png

    4. Choose Automatic as the Provisioning Mode.

    1c.png

    5. In the Admin Credentials section:

    Tenant URL is: https://yourdomain.udemy.com/scim/v2 (yourdomain is the url for your Udemy Business account)

    Secret Token: This is a ‘Bearer’ token that you can generate or view inside your Udemy Business account. (go to Manage > Settings > User Access to get the Secret Token)

    6. Click Test Connection to check that it’s working correctly.  

    Optional: You can enter an email address if you wish to receive alerts from Azure about errors.

    1d.png

    7. In Mappings:

    Check the attribute mapping:

    1e.png

    Azure SCIM Attribute.png

    Confirm that the required attributes below are added in the customappsso Attribute as these fields are required for SCIM provisioning to function within Udemy.

    Supported attributes

    SCIM attribute Required? Description
    emails[type eq "work"].value Yes Email of the user. Must be unique
    userName Yes The userName from the IdP. Must be unique.
    active Yes Flag to deactivate/reactivate users
    externalId Yes The externalId of the user from IdP. Must be unique.

    urn:ietf:params:scim:schemas:extension:

    enterprise:2.0:User:employeeNumber

    		 Yes Returns employeeNumber field from EnterpriseSchema and store it as external_id field. Should match the attribute you want sent to externalId.
    name.givenName No Given name of user. Even though they are not required, we recommend always specifying those attributes since it’ll make it easier to identify users.
    name.familyName No Family name of user. Even though they are not required, we recommend always specifying those attributes since it’ll make it easier to identify users.
    name, { givenName, familyName } No Given name and family name of the user. Even though they are not required, we recommend always specifying those attributes since it’ll make it easier to identify users.
    title No User’s job title, i.e. “Senior Engineer”

    urn:ietf:params:scim:schemas:extension:

    udemy:2.0:User:licensePoolName

    		 No The license pool name

    Edit_attribute.jpg

    Confirm the attribute Switch([IsSoftDeleted], , "False", "True", "True", "False") is mapped to active which allows the deactivation of users to be passed over.

    mapping_type.jpg

    8. Scroll down to the bottom of the User Attributes Mapping and enable Show advanced options.

    Select Edit attribute list for customappsso and enabled Exact case for both id and userName

    9. Go back to the main provisioning setting screen:

    1h.png

     

    10. Choose the Scope of how you want to sync your users and groups.

    1i.png

    You can sync only users and groups who are assigned the Udemy Business app if you need to restrict access to certain employees or departments. Or, you can sync all users and groups if every employee is going to have access.

    1j.png

    In order to provision more users and groups with Udemy Business access:

    11. Click Users and groups

    users_and_groups.png

    12. Click on Add User (which will give you the option to add both Users and Groups)

    Select all users or the groups you want to add to the application and click Select.

    Add_assignment.png

    Troubleshooting

    In relation to Mappings:

    User_mapping.png

    If you experience this error when provisioning:

    {"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"status":400,"detail":"{'emails': ['This field is required.']}"}

    You should change the mapping of the User.

    Edit_attribute.png

    emails[type eq "work"].value needs to be mapped to userPrincipalName that is, if userPrincipalName is where the email is.

    If you go to the user profile, you should be able to see which field contains the email there.

    user_profile.png

    For any errors provisioning users, you can view more details by looking into the provisioning logs.

    • You can obtain this log by going to the Udemy App on Azure > Provisioning > Provisioning Logs > Search for the affected user > Troubleshooting & Recommendations.
    • If needed, open a support ticket and provide a screenshot of the Azure provisioning logs so we can take a look at what failed.

    Read article

  • Configure SCIM Provisioning With OneLogin

    Once Single Sign-on (SSO) is set up you can then configure System for Cross-domain Identity Management (SCIM) provisioning in OneLogin with Udemy Business. This will allow you to provision, deprovision, create groups, manage group membership and change user profile details like name and email address in OneLogin, which automatically updates Udemy Business. You will no longer need to update both OneLogin and Udemy Business separately with these actions as it will all be synced from OneLogin.

    This article outlines how you can configure SCIM provisioning with OneLogin. 

    How to enable SCIM Provisioning

    To enable SCIM Provisioning for your Udemy Business account, first go to your Udemy Business account and access Manage > Settings > Provisioning (SCIM).

    Click Start Setup and follow the instructions to enable SCIM and generate the Secret Token (Bearer token) which you then need to save in OneLogin.

    1_21.png

    Next, access your OneLogin account and go to your Udemy Business SSO app and follow the steps below to get set up. 

    Additional information regarding how to provision users is also available in One Login's support center.

    1. In the admin panel click on the applications tab:

    2_21.png

    2. Navigate to the “Configuration” tab. Inside the “Configuration” tab, input the SCIM bearer token from your Udemy Business account that was generated above, and set to “Enabled”:

    3_21.png

    3. Next, navigate to the “Provisioning” tab, and check the “Enable provisioning” box:

    workflow_enable_provisioning.png

    Creating a rule to sync a user’s group with Udemy Business

    OneLogin uses the concept of “rules” in order to sync a user with a particular group in your Udemy Business account. There are many ways to create rules based on your different requirements for syncing groups. The following is one specific example of how to create a rule to sync a user with a group called “Engineers”.

    1. Navigate to the “Rules” tab and select “Add Rule”:

    rules_.png

    2. Prerequisite: Before moving to the next step, please contact our Support Team and request that they enable the feature flag that will allow SCIM groups to be pulled from Udemy Business. With this feature enabled you can pull the existing groups from Udemy Business and access them in OneLogin.

    3. Inside of the “Edit Mapping” screen is where you can configure the logic for your rule. In this example, we create a rule where the logic is “If the Group of the user is Engineering Group then the action is set the user’s group in Udemy Business to Engineers”: In order to pull groups “From Existing” in Udemy Business - you will need to refresh entitlements.

    actions.png

    4. Navigate to the “Parameters” tab:

    OneLogin parameters.png

     

    To send over the externalId value from OneLogin to Udemy, please make sure to have the parameter urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber added.
    Note: adding parameters might not take effect immediately as OneLogin does a parameter sync daily.

    5. Click on the “Groups” field:

    groups_field.png

    6. Check the “Include in User Provisioning” box and save:

    9_21.png

    7. Now, after adding a user in OneLogin and setting that user’s group to “Engineering Group”:

    10_21.png

    8. Once the user is added to the Udemy Business application and synced, based on the rule, this user will be added to the “Engineers” group in your Udemy Business account:

    11_21.png

     

    Read article

  • Automating User and Group Management With SCIM

    Udemy Business supports user and group access and identity management with the System for Cross-domain Identity Management (SCIM) standard. SCIM is used by Single Sign-On (SSO) services and Identity Providers to manage people across a variety of apps and tools, including Udemy Business.

    SCIM can be a great option for organizations looking to maximize scale and security, as well as minimize friction in user management for Udemy Business.

    What you can do with SCIM:

    • Automatically provision licenses and access to users and groups from your Identity Provider (provisioning).
    • Automatically deactivate users and groups from your identity provider (deprovisioning).
    • Reactivate users who were previously deprovisioned (provided the user’s personally identifiable information has not been anonymized).
    • Update user details: name, email address. 
    • Create, remove, or edit groups.
    • Manage group membership (users changing groups).

    What you cannot do with SCIM:

    • Delete User Personal Identifiable Information (PII) via SCIM on any Identity Provider.
    • Sync data from Udemy Business back to the Identity Provider.
    • Manage roles (admin, group admin, user).
    • Assign Udemy Business Pro licenses
    • Please note: SCIM-provisioned users will not receive an automatically-generated email invite to claim their Udemy Business license as they would if they were manually invited through the Udemy Business user management portal. We recommend your learning team send out a separate communication explaining how they can get access by logging in via their SSO provider. However, users who are reactivated via SCIM will receive an automatically-generated email from Udemy saying their account has been reactivated.

    Once you take any of the above supported actions, the data or change will automatically update in Udemy Business.

    Key points about SCIM Integration for your Udemy Business Account

    • Your SCIM integration setup will vary depending on the identity provider you use. 
    • Udemy Business supports SCIM Provisioning for the key identity providers and SSO services that offer access and identity management.
    • SCIM Provisioning is available to Enterprise Plan customers using Single Sign-on (SSO).
    • Users provisioned through SCIM in your SSO service will not take up a license until they join Udemy Business by signing in for the first time. When users are provisioned through SCIM but have not signed in for the first time, they will display on the All users page with a No License status.
      • For customers who have purchased Udemy Business Pro licenses for all users, Pro licenses will be automatically assigned when invitations are accepted by users, or when they authenticate via SSO/SCIM.
    •  Note:  When SCIM is enabled, Udemy uses the SCIM protocol for attribute mapping over SAML. Since groups is not a SCIM user attribute, groups will not pass via SAML if you previously mapped the attribute as part of a SAML only configuration.

    SCIM-managed users have a gray SCIM flag next to their name and email.  Users with the Status SCIM provisioned will not consume an active license until they login for the first time:

    How to enable SCIM provisioning

    To enable SCIM provisioning for your Udemy Business account, go to your Udemy Business account to Manage > Settings > Provisioning (SCIM). 

    Scroll to the SCIM Integration section. Next, follow the instructions to enable SCIM, choose your Identity Provider from the dropdown, and generate the credentials (Username and Password or Secret/Bearer token), which you then need to input into your Identity Provider as part of the configuration.

    provisioning_scim_start_setup.png

    Depending on which Identity Provider you use, follow the instructions in the appropriate guide below to complete the SCIM setup.

    Okta Configuration Guide 

    Azure AD Configuration Guide 

    OneLogin Configuration Guide

    For other IdPs or your own tools, please refer to the Udemy SCIM API Configuration Guide.

    How to disable SCIM provisioning

    To disable SCIM provisioning for your Udemy Business account (if you’re changing providers or no longer require SCIM) access Manage > Settings > Provisioning (SCIM).

    Scroll to the SCIM Integration section and click on the Disable Integration link and follow the instructions to disable SCIM. This will disable the integration from the Udemy Business side, but your IT team will need to disable the integration from the Identity Provider side also. 

    You can continue to use Udemy Business as usual, but you will need to manually update user and group information within the platform from now on.

    provisioning_scim_disable_integration.png

    Deprovisioning users with SCIM

    Note that Udemy Business users deprovisioned from your Identity Provider will be deactivated within Udemy Business.  We first deploy this “soft delete” to enable you to preserve learner history, in the case of reactivating these users at a later point, and to prevent accidental, irreversible, anonymization of user data.  If you wish to permanently delete a user and all their data, please follow the instructions below:

    Deleting PII for SCIM-managed learners

    If you wish to disconnect a learner from being managed by your IdP with SCIM, you can do so by first deprovisioning them in your SSO Active Directory, and then you can delete their PII in your Udemy Business account.

    If you need to manage a learner directly from within your Udemy Business account and not via your SSO IdP, and further, or you do not wish to delete their PII, please reach out to our support team for further assistance.

    Read article

  • Configure SCIM Provisioning With Okta

     

    This guide provides the steps required for existing Okta and Udemy Business customers to configure automatic provisioning, deprovisioning, profile updates and group management of Udemy Business users and groups using System for Cross-domain Identity Management (SCIM 2.0).

    Notes:

    • If you already have SSO sign on enabled for Udemy Business in Okta, you do not need to reconfigure SSO again. Just look for the Provisioning tab under Applications in Okta to set SCIM up.
    • If you had SSO set up from a manual configuration by one of our team, you should add our new Udemy Business app into your Okta account. You will find this in Applications by searching for Udemy Business. Because this is a new version of our app in Okta, existing customers might be required to reconfigure Single Sign On (SSO) before enabling SCIM Provisioning. (step by step instructions below)
    • Users provisioned through Okta will not consume an active license until they log into the Udemy Business application for the first time. 
    • SCIM-managed users and groups can only be changed in Okta.
    • When SCIM is enabled, Udemy uses the SCIM protocol for attribute mapping over SAML. Since groups is not a SCIM user attribute, groups will not pass via SAML if you previously mapped the attribute as part of a SAML only configuration.

    Contents

    • Features
    • Requirements
    • Configuration Steps
    • Schema Discovery
    • Troubleshooting Tips

    Features

    The following SCIM provisioning features are supported:

    • Provision Users from Okta
      • Users assigned the Udemy Business app in Okta will be provisioned in Udemy Business.
      • Note that users will not receive an automatically-generated invite email if they are SCIM provisioned from Okta.
    • Push Profile Updates
      • Updates made to the user's profile through Okta will be pushed to Udemy Business for users who are associated with Udemy Business in Okta.
    • Push User Deactivation
      • Deactivating the user or disabling the user's access to the application through Okta will deactivate the user on Udemy Business and remove them from all groups.
      • Note: Deactivated users will retain their learning data for reporting purposes or future reactivation.  To permanently delete a SCIM-managed deactivated user you will first need to break the SCIM connection for that user, which Udemy Business support can assist with.  
    • Reactivate Users
      • Users can be reactivated in Udemy Business by reassigning the app to that user through Okta.
      • Note that reactivated users will receive an automatically-generated email from Udemy saying they’ve been reactivated.
    • Group Push
      • Groups and their memberships will be pushed to Udemy Business. Manage groups is limited to groups pushed originally from Okta as we do not send information of groups created on Udemy Business.

    SCIM-managed users have a gray SCIM flag next to their name and email.  Users with the Status SCIM provisioned will not consume an active license until they login for the first time:

    Configuration Steps

    If you have not enabled SSO for Okta or if you had SSO set up from a manual configuration by our team, please complete the Okta SSO configuration steps here first.

    • You can avoid any SSO downtime by hiding the Udemy Business tile in your Okta dashboard until the new SSO and SCIM configuration is complete. 
    • Beside Application Visibility click ‘Do not display application icon to users’

    1. To start, click on the Provisioning tab then Configure API integration.

    configure_api_integration.png

    2.  Click on Enable API Integration and add your subdomain, domain (udemy.com), CLIENT_ID as username, and SECRET_ID as password. 

    [You can generate or view these credentials in your Udemy Business account by accessing the Provisioning (SCIM) page under Manage -> Settings.]

    3. Click on Test API Credentials and you should see a message indicating that you’ve successfully completed your SSO integration. If not, please send a message to the Udemy Business Support Team with the given error message.


    4. Click on Save and you will be redirected to the Application Provisioning configuration page.


    provisioning_to_app_save.png

    5. On To App link click on Edit to enable individual features. To use all the capabilities we recommend to enable Create Users, Update User Attributes and Deactivate Users on this page.

    provisioning_to_app_edit.png
    6. Click on Save

    7. Click on the Assignments tab to assign Udemy Business to single users or entire groups. Assigned users will be automatically provisioned after being added, automatically modified when changes are made to their profiles, and automatically deactivated when they are removed from assignments.

    8. Click on the Push Groups tab to send groups and their membership information to Udemy Business.

    push_groups_to_ub.png
    9. Click on + Push Groups and select the groups you want to push to Udemy Business.

    You will be able to select each group, or you can create an automatic rule.

    find_groups_ub.png
    10. Select the group search criteria and fill the requested information for the groups you would like to send information to Udemy Business.

    push_groups_by_name.png

    11. After selecting the group, check Push group memberships immediately to send not only the group but the members within the group as soon as you select the group, and click on Save.

    12. Follow the previous steps for groups selection for all groups you would like to send to Udemy Business.

    Note: Udemy Business will not allow changes to SCIM-managed users or groups after setup.

    Read article

  • Configure SCIM Provisioning With Udemy’s SCIM API

    Overview

    System for Cross-Domain Identity Management (SCIM) is a standard API for automating user and group provisioning/deprovisioning, and updating user and group data from the customer’s Identity Provider (IdP) into the Udemy Business account.  SCIM is supported by a number of Identity Providers such as Okta, Azure AD, and OneLogin.  You can also utilize the Udemy Business SCIM API for other IdPs or home-grown tools.

    If your organization uses one of the following IdPs, please instead refer to our guides below for configuring SCIM:

    SCIM uses a standardized REST API with data formatted in JSON. Udemy Business supports version 2.0 of the SCIM standard. The API is available for all customers that are on the Enterprise plan.

    Udemy Business SCIM API supports the following features: 

    • Provisioning users
    • Deprovisioning users (deactivation)
    • Changing email addresses
    • Changing user details
    • Provisioning groups
    • Adding/removing users to groups

    SCIM protocol description

    SCIM Protocol is an application-level REST protocol for provisioning and managing identity data on the web. The protocol is client-server where the client is the Identity Provider (IdP) and the server is Udemy Business.

    The basic flow is:

    • When access to Udemy Business is granted to the user in the IDP by the customer, the IdP sends us a request to check if the specific user exists in our database. They issue a User search request by an attribute like userName or email.
    • If the user does not exist, the IdP sends a request to create a user.
    • If the user exists, the IdP sends an update request for the user.
    • When access to Udemy Business is revoked, the IdP sends us a request to deactivate the user from our database.
    • IdP can also send requests to change user details.

    How to access the API?

    In order to obtain the authorization credentials to connect to the SCIM API, you will have to set up SCIM integration via Manage -> Settings -> Provisioning (SCIM) page in your Udemy Business account. Note that only Admins have access to this page. 

    Click Start Setup.

    provisioning_scim.png

    In the next step, select Choose provider, then Custom.

    select_provider.png

    Click Generate token.

    generate_token.png

    On this screen, click Copy to copy the Bearer token to the clipboard.

    copy_bearer_token.png

     

    You will need to include Authorization HTTP header with the Bearer token in your requests, for example:

    GET /scim/v2/Users HTTP/1.1
    Host: myorganization.udemy.com
    Accept: application/scim+json
    Authorization: Bearer <enter you Bearer token here>
    Content-Type: application/scim+json

    Udemy Business SCIM API uses the HTTP protocol and is only available over a secure HTTPS connection.

    The base URL for the API is: https://<yoursubdomain>.udemy.com/scim/v2/.

    If you are developing an application to interact with the Udemy Business SCIM API, it is recommended to refer to the SCIM RFCs included at the end of this document. Udemy Business SCIM API implementation is compliant with the standard.

    Rate limiting

    Udemy Business applies rate limiting to the SCIM API in accordance with the standard HTTP rate limiting protocol. If your request is ratelimited, you will receive an HTTP 429 response and you’re supposed to wait and retry according to what is specified in the Retry-After header.

    SCIM API endpoints

    Informational Endpoints

    These endpoints are informational and serve to configure the clients. They do not require authentication, so you don’t need to include the Authorization header when accessing these endpoints.

    GET /ServiceProviderConfig

    Returns details about Udemy Business SCIM implementation including which methods are supported.

    GET /Schemas

    Returns information about the schemas that our SCIM implementation supports. Supported schemas are Users and Groups.

    GET /Schemas/Users

    Returns all attributes that we support for User resources.

    GET /Schemas/Groups

    Returns all attributes that we support for Group resources.

    User endpoints

    Using these endpoints you can list users, filter by attributes, add new users, update  users’ information, or deactivate/anonymize users. 

    If the SCIM API does not return all users please contact Udemy Business Support.

    Supported attributes

     

    SCIM attribute Required? Description 
    emails[type=”work”]]['value’]
    		 Yes Email of the user. Must be unique 
    userName
    		 Yes The userName from the IdP. Must be unique. 
    active
    		 Yes Flag to deactivate/reactivate users 
    externalId
    		 Yes The externalId of the user from IdP. Must be unique. 
    urn:ietf:params:scim:schemas:extension:
    enterprise:2.0:User:employeeNumber
    		 Yes Returns employeeNumber field from EnterpriseSchema and store it as external_id field 
    name.givenName
    		 No Given name of user. Even though they are not required, we recommend always specifying those attributes since it’ll make it easier to identify users. 
    name.familyName
    		 No Family name of user. Even though they are not required, we recommend always specifying those attributes since it’ll make it easier to identify users. 
    name, { givenName, familyName }
    		 No Given name and family name of the user. Even though they are not required, we recommend always specifying those attributes since it’ll make it easier to identify users. 
    title
    		 No User’s job title, i.e. “Senior Engineer” 
    groups
    		 No SCIM group(s) that the user belongs to


    Note: If you specify any other attribute that is not on this list, it will be ignored.

    GET /Users

    Returns a paginated list of users, 12 users per page by default. You can pass in

    count

    and

    startIndex

    parameters to paginate through the result set. For example:

    GET /scim/v2/Users?startIndex=1&count=100 HTTP/1.1

     Host: myorganization.udemy.com

     Accept: application/scim+json

     Authorization: Bearer <enter you Bearer token here>
    startIndex
    • is the 1-based index of the first result in the current set of list results (offset) 
    • count
      is the number of resources returned in a list response page (limit). You can retrieve no more than 1000 users in a single request. If this item is omitted it will default to 12.

    Example request

    GET https://demo.udemy.com/scim/v2/Users 
    {
    "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 18,
    "startIndex": 1,
    "Resources": [
    {
    "id": "KwLzN3",
    "externalId": "00u3mlhj4x1E482sK5d7",
    "userName": "firstName.lastName@domain.com",
    "name": {
    "givenName": "firstName",
    "familyName": "lastName",
    "formatted": "firstName lastName"
    },
    "emails": [
    {
    "value": "firstName.lastName@domain.com",
    "type": "work",
    "primary": true
    }
    ],
    "title": "",
    "active": true,
    "groups": [
    {
    "value": "NZOaw",
    "display": "Group Test",
    "$ref": "https://demo.udemy.com/scim/v2/Groups/NZOaw"
    },
    {
    "value": "dn1K8",
    "display": "NewGroup2",
    "$ref": "https://demo.udemy.com/scim/v2/Groups/dn1K8"
    }
    ],
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "meta": {
    "resourceType": "User",
    "location": "https://demo.udemy.com/scim/v2/Users/KwLzN3",
    "created": "2022-01-19T01:11:59Z",
    "lastModified": "2024-11-22T21:58:48Z"
    },
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "64e63"
    }
    },
    [...]
    ],
    "itemsPerPage": 12
    }

     

    GET /Users?filter=

    This endpoint is used to filter users by specific attributes. For example, it is possible to search by userName attribute:

    GET /Users?filter=userName eq "example..name”

    Note: In the example above, you will need to URL encode the URL parameters so the URL becomes:

    GET /Users?filter=userName%20eq%20%22example.name%22

    This will return a list of user resources. If there are no results, an empty list will be returned.

    GET Users?filter=groups.value eq "{SCIM_Group_ID}"

    This will return all users who belong to this SCIM Group

    The supported filters are:

    userName
    externalID
    emails[type eq=”work”]
    groups

    The supported operators are:

    and
    eq

    Response:

    • HTTP status code 200 with the list of entities on success
    • HTTP status code 501 if an unsupported filter is supplied
    POST /Users

    This endpoint is used to create (provision) new users in Udemy Business. 

    The response will contain an

    id

    attribute which should be used when referring to this user in all subsequent requests.

    Note that:

    • New users created this way will not take up a license until they sign in for the first time.
    • If there was an existing pending invitation for this user, it will get used at this point.
      The user will get added to groups, be assigned appropriate role/course assignments according to what is specified in the invitation.
    • An attempt to create a user that already exists in Udemy Business will cause the user to become SCIM managed (displayed with a small link icon on the Manage Users page). Note that the user's status and license usage will not be changed. If the user was active,  they will remain active and if the user was deactivated they will remain deactivated.

    Example request

     

    POST https://demo.udemy.com/scim/v2/Users 
    {
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "active": true,
    "emails": [
    {
    "primary": true,
    "type": "work",
    "value": "demo.user@test.com"
    }
    ],
    "externalId" : "externalIdValue",
    "meta": {
    "resourceType": "User"
    },
    "userName": "DemoTest",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "externalIdValue"
    },
    "name": {
    "familyName": "Test",
    "formatted": "formatted",
    "givenName": "Demo"
    }
    }

    Example response

    {
    "id": "MPD698",
    "name": {
    "givenName": "Demo",
    "familyName": "Test",
    "formatted": "Demo Test"
    },
    "emails": [
    {
    "value": "demo.user@test.com",
    "type": "work",
    "primary": true
    }
    ],
    "title": "",
    "active": true,
    "groups": [],
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "meta": {
    "resourceType": "User",
    "location": "https://demo.udemy.com/scim/v2/Users/MPD698",
    "created": "2024-12-27T22:00:25Z",
    "lastModified": "2024-12-27T22:00:26Z"
    },
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "externalIdValue"
    },
    "userName": "DemoTest",
    "externalId": "externalIdValue"
    }

     

    Response:

    • HTTP status code 201 and the user’s resource on success
    • HTTP status code 409 if the member with the same userName already exists in the Organization
    • HTTP status code 400 with the error details in the response body if the request did not pass validation
    GET /Users/<id>

    This endpoint is used to retrieve user details for a specified user.

    id

    parameter in the request above is a unique identifier that was returned when the user was created using SCIM or when listing all existing users.

    Response:

    • HTTP status code 200 with the user resource on success
    • HTTP status code 404 if the user has not been found
    PUT /Users/<id>

    This endpoint is used to replace (overwrite) user details in Udemy Business. If specified, attribute active can be used to deactivate or reactivate the user.

    Example request:

    PUT https://demo.udemy.com/scim/v2/Users/MPD698
    {
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "MPD698",
    "userName": "demo.user@test.com",
    "externalId": "NewExternalID",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "NewExternalID"
    },
    "name": {
    "givenName": "demo",
    "familyName": "user"
    },
    "emails": [
    {
    "value": "demo.user@test.com",
    "type": "work",
    "primary": true
    }
    ],
    "active": true
    }

    Example response

    {
    "id": "MPD698",
    "name": {
    "givenName": "demo",
    "familyName": "user",
    "formatted": "demo user"
    },
    "emails": [
    {
    "value": "demo.user@test.com",
    "type": "work",
    "primary": true
    }
    ],
    "title": "",
    "active": true,
    "groups": [],
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "meta": {
    "resourceType": "User",
    "location": "https://demo.udemy.com/scim/v2/Users/MPD698",
    "created": "2024-12-27T22:00:25Z",
    "lastModified": "2024-12-27T22:17:52Z"
    },
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "NewExternalID"
    },
    "userName": "demo.user@test.com",
    "externalId": "NewExternalID"
    }

     

    Response:

    • HTTP status code 200 and the updated user resource
    • HTTP status code 404 if the user doesn’t exist. 
    • HTTP status code 400 in case of an attempt to deactivate an organization owner.
    PATCH /Users/<id>

    This endpoint is used to make partial updates to the user details in our system, meaning that you can use it to change only some attributes of the user. This is in contrast to PUT which replaces the entire user. 

    It can contain the attribute active which will cause the user to be deactivated or reactivated.

    • The body of each request MUST contain the "schemas" attribute with the URI value of "urn:ietf:params:scim:api:messages:2.0:PatchOp".
    • The body of an HTTP PATCH request MUST contain the attribute "Operations", whose value is an array of one or more PATCH operations.  Each PATCH operation object MUST have exactly one "op" member, whose value indicates the operation to perform and MAY be one of "add", "remove", or "replace".
    • The “path” attribute can be empty, in this case “value” should be a dictionary in the format of {“path”: “value”}.

    Example request

    PATCH https://demo.udemy.com/scim/v2/Users/MPD698 
    {
    "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [ 
    {
    "op": "replace",
    "path": "userName",
    "value": "DemoUserName"
    }
    ]
    }

    Example response

    {
    "id": "MPD698",
    "name": {
    "givenName": "demo",
    "familyName": "user",
    "formatted": "demo user"
    },
    "emails": [
    {
    "value": "demo.user@test.com",
    "type": "work",
    "primary": true
    }
    ],
    "title": "",
    "active": true,
    "groups": [
    {
    "value": "5ypNz",
    "display": "NewGroup",
    "$ref": "https://demo.udemy.com/scim/v2/Groups/5ypNz"
    }
    ],
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "meta": {
    "resourceType": "User",
    "location": "https://demo.udemy.com/scim/v2/Users/MPD698",
    "created": "2024-12-27T22:00:25Z",
    "lastModified": "2024-12-27T22:17:52Z"
    },
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "NewExternalID"
    },
    "userName": "DemoUserName",
    "externalId": "NewExternalID"
    }

    Response:

    • HTTP status code 200 with the updated user’s resource on success
    • HTTP status code 404 if the user was not found
    • HTTP status code 400 if attempting to deactivate an organization owner or in case of an invalid operation.

    Group endpoints

    Supported attributes

    SCIM attribute

    Required?

    Description

    		 
    displayName

    Yes

    Group title. Must be unique among all Udemy Business groups.

    		 
    externalId

    No

    The externalId of the group from the Identity Provider

    Note: If you specify any other attribute that is not on this list, it will be ignored.

    GET /Groups

    This endpoint is used to get a paginated list of all provisioned groups. Include startIndex and count query string parameters to paginate through the results. 

    Bear in mind that only groups created using SCIM will be returned. Groups created from Udemy Business will not be returned.

    Example request

    GET https://demo.udemy.com/scim/v2/scim/v2/Groups
     "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 6,
    "startIndex": 1,
    "Resources": [
    {
    "id": "NZOaw",
    "displayName": "Group Test",
    "members": [
    {
    "value": "KwLzN3",
    "display": "firstName lastName",
    "type": "User",
    "$ref": "https://demo.udemy.com/scim/v2/Users/KwLzN3"
    },
    {
    "value": "eBmzpr",
    "display": "user four",
    "type": "User",
    "$ref": "https://demo.udemy.com/scim/v2/Users/eBmzpr"
    }
    ],
    "externalId": null,
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "meta": {
    "resourceType": "Group",
    "location": "https://demo.udemy.com/scim/v2/Groups/NZOaw",
    "created": "2024-08-23T22:26:48Z",
    "lastModified": "2024-08-23T22:26:48Z"
    }
    },
    [...]
    ],
    "itemsPerPage": 12
    }
    GET /Groups?filter=

    This endpoint is used to filter groups by specific attributes. For example, it is possible to search by displayName attribute:

    GET /Groups?filter=displayName eq "Marketing”

    This will return a list of group resources. If there are no results, an empty list will be returned.

    Note that you will need to url encode the parameters, so the request becomes:

    GET /Groups?filter=displayName%20eq%20%22Marketing%22

    The supported filters are:

    displayName
    externalId
    Id
    member.value

    The supported operators are:

    and
    eq

    Response:

    • HTTP status code 200 with the list of entities on success
    • HTTP status code 501 if the non-supported filter is used
    POST /Groups

    This endpoint is used to create (provision) new groups in Udemy Business. 

    Response:

    • HTTP status code 409 If the provisioned group with the same name already exists in the org, we return 409 (Conflict) with a scimType error code of uniqueness.
    • When the group has been created successfully, we return the full representation of the group with HTTP status code 201 (Created) together with the Location header that contains the URL of the create group resource.
    GET /Groups/<id>

    This endpoint is used to fetch the group details from Udemy Business. 

    Response:

    • HTTP status code 200 and a group resource
    • HTTP status code 404 if the group has not been found
    POST /Groups

    This endpoint is used to create (provision) new groups in Udemy Business.

    Warning: When using the POST or PUT /scim/v2/Groups endpoint to create groups, do not include the members attribute in the request. Any members specified will be ignored. To add users to a group, first create the group, then make separate calls to the PATCH /scim/v2/Groups/ 

    Example request 

    https://demo.udemy.com/scim/v2/Groups 
    {
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "Group1",
    "externalId": "234523"
    }

    Example response

    {
    "id": "vREOw",
    "displayName": "Group1",
    "members": [],
    "externalId": "234523",
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "meta": {
    "resourceType": "Group",
    "location": "https://demo.udemy.com/scim/v2/Groups/vREOw",
    "created": "2025-01-15T22:24:54Z",
    "lastModified": "2025-01-15T22:24:54Z"
    }
    }
    PUT /Groups/<id>

    This endpoint is used to replace the group details in Udemy Business.

    Warning: When using the POST or PUT /scim/v2/Groups endpoint to create groups, do not include the members attribute in the request. Any members specified will be ignored. To add users to a group, first create the group, then make separate calls to the PATCH /scim/v2/Groups/ 

    Example request

    PUT https://demo.udemy.com/scim/v2/Groups/vREOw 
    {
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "Group1",
    "externalId": "MPD699"
    }

    Example response

    {
    "id": "vREOw",
    "displayName": "Group1",
    "members": [],
    "externalId": "MPD699",
    "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "meta": {
    "resourceType": "Group",
    "location": "https://demo.udemy.com/scim/v2/Groups/vREOw",
    "created": "2025-01-08T21:12:53Z",
    "lastModified": "2025-01-15T22:35:55Z"
    }
    }

    Response:

    • HTTP status code 200 and the updated group resource 
    • HTTP status code 404 if the group doesn’t exist. 
    •  
    PATCH /Groups/<id>

    This endpoint is used to make partial updates to group details in Udemy Business. 

    The PATCH endpoint is more tricky than others, as it supports different kinds of operations (and their combinations are possible):

    Example request

    PATCH https://demo.udemy.com/scim/v2/Groups/5ypNz 
    { "schemas": 
    ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":[
    {
    "op":"add",
    "path": "members",
    "value":[{
    "display": "demo user",
    "$ref":"https://demo.udemy.com/scim/v2/Users/MPD698",
    "value": "MPD698"
    }
    ] 
    } 
    ]
    }

    Example response

    204 No Content
    • replace operation changes the specified value. In our case it’s either group name or members.
    • remove operation removes a member from the group.
    • add operation adds members to the group.

    The rules are the following:

    • We never remove unprovisioned members from the group (in case of `replace` members operation, for example).
    • PATCH request, regardless of the number of operations, SHALL be treated as atomic.

    The input validations are the following:

    • The body of each request MUST contain the "schemas" attribute with the URI value of "urn:ietf:params:scim:api:messages:2.0:PatchOp".
    • The body of an HTTP PATCH request MUST contain the attribute "Operations", whose value is an array of one or more PATCH operations.  Each PATCH operation object MUST have exactly one "op" member, whose value indicates the operation to perform and MAY be one of "add", "remove", or "replace".
    • The “path” attribute can be empty, in this case “value” should be a dictionary in the format of {“path”: “value”}.
    • For “Remove” operation the “members” path is required.
    • For the “Add” operation either “members” or “externalId” “path” should be present.
    • For “Replace” operation “members” path may be present. If it’s not there it means that we are replacing the group details (like group name) but not members.

    Note:

    • Assigning/unassigning users to a group happens asynchronously, so the changes won’t be reflected immediately in Udemy Business.
    • We do not support nested groups, so they will be ignored during this request.

    Response:

    • HTTP status code 204 if the operation was successful.
    • HTTP status code 404 if the group does not exist.
    • HTTP status code 404 with the error details if there is an attempt to assign a group to a user that’s not a member of the organization.
    • HTTP status code 400 with the error details in the response body if the request did not pass the validation
    DELETE /Groups/<id>

    This endpoint is used to remove or deprovision a group in Udemy Business. 

    The rules are the following:

    • If the group contains non-provisioned members, remove provisioned users from the group, delete `OrganizationSCIMGroup` record.

    Response:

    • HTTP status code 204 if the operation was successful.
    • HTTP status code 404 if the group does not exist.

    Further Reading

    Read article

  • Using Approved Email Domains to Give Users ‘Self-serve’ Access to Udemy Business

    We have two ways to provide your users with access to your Udemy Business account - through single sign-on (SSO) and by invitation sent by admins/group admins.

    This feature is an additional option if you use the invitation process, which gives your users a way to trigger the invitation email themselves from your account landing page (eg. company.udemy.com), once they use an approved/verified email address domain that has been pre-set by you, the admin.

    How to approve an email address domain

    On the page in Settings called Email Domain Access, admins can specify an email address domain (or multiple domains) that are approved for joining your Udemy Business account.

    email_domain_access.png

    This feature is available for both Team and Enterprise plans - but setting up the approved email domain in the Email Domain Access page is only accessible by owners and admins, not group admins.

    Sharing your account landing page URL for users to sign up

    You can share your Udemy Business account landing page URL with the users and groups in the organization who should have access, eg. by Slack, email, wiki, intranet or simply add the link in your learning management system (LMS).

    When a user accesses your account landing page URL they can enter their email address to sign up, once the email address entered matches an approved email domain that was pre-set by the admin.

    Please note: To maintain a secure and reliable platform, we require email validation when signing up for a new account. If you are experiencing issues, please review our troubleshooting steps.

    UB_login.jpg

    Once they enter an approved email address, they get an on-screen instruction to check their email to verify their account.

    check_your_email_for_invitation.png

    License usage and verification

    Users must complete signing up for their account in order to claim their license. 

    If there are no licenses available we present the user with the message below to contact their manager or IT department.

    all_licenses_have_been_allocated.png

    Users will then need to verify their account information, via the verification email they received which contains a link. The verification link will expire in one hour*. Once they’ve verified their account, they’ll be able to sign up, by adding their name, email and password.

    *Please note that Single Sign-On (SSO)/System for Cross-Domain Management (SCIM) users will not be put through this verification flow.

    send_verification_email.png

    activate_account_email.png

    If the email address the user enters does not match the approved email domain, they will see the message below and will be prevented from signing up.

    not_invited_to_this_account.png

    If there are no licenses available we present the user with the below message to contact their manager or IT department.

    no_licenses.png

    Users that sign up through the approved email domain process will show in the Pending Invitations screen in Manage Users, but they will be distinguished as ‘Invited through approved email’.

    invited_through_approved_email.png

    This feature is available for both Team and Enterprise plans - but setting up the approved email domain in the User Access page is only accessible by owners and admins, not group admins.

    Read article