In order to allow a new User access to the Nimbus UI (either Portal or Admin functionality), the User needs to be made known as a configurable and referable data entity in Nimbus.
💡Access to your User Directory (Entra ID)
Precondition: As stated in our Nimbus App Permissions Nimbus uses delegated permissions to search for Users in your Microsoft Entra ID. If these permissions are granted by a Tenant Administrator, any of the existing Nimbus Admin Roles – e.g. a delegated Tenant Administrator – can search for and add a User using their display name.
💡Regardless of the way you add Services and Users to Nimbus, your Entra ID User directory remains the "source of truth".
⮑ Once the User is added, Nimbus uses the O365 ID for internal mapping and User identification. All other Data will be synchronized (UPN, First Name, Last Name, Avatar, etc.) and made available for internal search, e.g. via Attendant Console to perform call transfers.
Considerations before creating Users
Any User that already exists in any Nimbus Service does not need to be recreated / added again. Their user account be upgraded for further licenses and Use Cases. A User can act in multiple different Roles simultaneously.
🤔 Does Nimbus create or change any existing Users?
Nimbus by itself does not create new Users in your directory, nor will it write over any existing fields. Users are authenticated using the Organization Units and Role Access Concept, with Entra ID (O365 ID) and Single-Sign-On details as verification “source of truth”.
Service to User assignment
User Assignment Types
INC User Assignment Types
Each Nimbus service can be of a different user assignment type that determines how users are associated to this service:
- MS Teams-based: Directly tied to your MS Teams "Teams" as determined during Service Provisioning. Users get automatically added and synced to a Nimbus service.
- Skill-based: Applies for manually created services via Service Administration. Requires skill-assignment from users you assign to the service from within your tenant directory.
- None: Has no users, but can be configured by any administrator. Used for IVR or first-level redirection services.
☝ Important to know: The user assignment type is fixated when a service was either provisioned via MS Teams or manually created via Service Administration, e.g. for IVR or skill-based distribution purposes. A switch between MS Teams-based and Skill-based services is not possible due to how individual users are configured and how Nimbus Features operate.
🤔 Is user assignment tied to licensing?
The method of user assignment per Service type, and related feature licenses not co-dependent on a technical level. However certain ways of managing user permissions may be preferrable, depending on your requirements and how you provision new services in future.
| User Assignment | Advanced Routing | Enterprise Routing |
Contact Center |
Description |
|---|---|---|---|---|
| MS Teams-based | ✅ | ✅ | 🔍 Relevant if you want to stick to MS Teams-based user sync but use Contact Center Features |
MS Teams-based user assignment is the most common scenario for new Advanced Routing and Enterprise Routing licensed services. Permissions are automatically determined by the role in the MS Teams channel, minimizing the administrative effort to onboard and configure new users. |
| None | ✅ | ✅ | ✅ | Services with user assignment type "none" are generally used for IVR or automated redirection. They can be created manually and out outside of an MS Teams channel restriction |
| Skill-based | ❌ | ❌ | ✅ |
The main use case for Contact Center services is setting up Distribution Policies to escalate calls based on Skills and Responsibilities. The Distribution Order guarantees that users get selected in a very targeted manner. With adjustments of their skills and Duty Profiles users can opt-in or out of certain distribution policies, e.g. based on time of day, workload, current responsibilities. Adding and removing of users is very flexible, e.g. across departments and outside of MS Team-based constraints. |
🤔 How does this affect my service operation?
Yes the user assignment greatly determines how a service (and its users) are managed and interact with each other in future.
💡 MS Teams-based services are tied to one dedicated channel in the Teams client.
The Service name and all channel users are in sync with and actively used by Nimbus for task distribution. Most interaction is tied to the channels within that team, e.g. Voice Messages, General chat.
💡 Skill-based services allow users to participate in multiple services simultaneously.
- The individual services are NOT tied to using MS Teams channels as central point of communication and user management. The removal of a dedicated Teams channel also removes the possibility for a single channel for Voice Messages, also opening up potential data access and GDPR compliance risks.
-
Skill-based services also add configuration complexity:
- Users on skill-based services are managed via Agent Service Settings per service. This can be done by any team owner.
- Optionally users can get Skills and Responsibilities assigned for escalated service task distribution. A Distribution Policy assigned to each service determines how new incoming tasks are distributed among users, depending on their responsibility and expertise.
- 💡 Good to know: Users are also not "Active" on skill-based services per default. Instead, they control their own service availability via configurable Responsibility Profiles.
💡None - Services with no users assigned
These services do not have users nor a specific MS Teams channel, and therefore don't use most of the abovementioned features. They only act as “gateway”, e.g. to route customers to actual services via IVR.
🤔 Does user assignment affect available features?
Yes, because certain features cannot operate “outside” of a given MS Teams channel context. While technically independent from the chosen service type (license) the user assignment type mandates which Nimbus Features are available. Here are some examples:
| Feature | User Assignment Type ► | MS Teams based | Skill- based | None |
|---|---|---|---|---|
| Workflow configuration | Adaptive Cards | ✅ | - | - |
| Voice message | ✅ | - | - | |
| Service Settings | Voice message channel | ✅ | - | - |
| Extensions tab | ✅ | ✅ | - | |
| Conversations Distribution section | ✅ | ✅ | - | |
| Setting of a Distribution Policy | - | ✅ | - | |
| New users immediately active | ✅ | - | - | |
| Reporting section | ✅ | ✅ | - | |
| Editable "Name" field on Service Settings | - | ✅ | ✅ | |
| Frontend UI | "Active" toggle for users | ✅ | - | - |
| Users switching Duty States / Responsibility Profiles | - | ✅ | - |
🤔 When should I create Nimbus Users manually?
This depends on the Nimbus Features you want to enable for your Users. Here are some example Use Cases:
| Use Case | Description |
|---|---|
| Contact Center Agent | In case you want to create a Contact Center service without a direct MS Teams "Team" connection you can add Users manually by searching within your O365/Azure User directory. By individually assigning Contact Center licenses to those Users you enable Skills and Responsibilities for skill-based distribution within any (future) Contact Center service type. |
| Frontpage Support / First Contact | Some Users may not directly participate in a Nimbus service, but use Luware Interact to directly communicate with customers via embedded Website widget. These Users need to be added to the Nimbus list before setting up Interact. |
| Custom Role | You may want assign a Contact Center license to a single User, e.g. to grant them Custom Roles valid within specific Organization Units. This gives you full control over which permissions this User actually has. |
💡Access to Service data: Manually added Users will get login access to the Nimbus Portal, but may not see any relevant reporting data until they are part of at least one service.
Adding a User manually
The default way to create a new User in Nimbus is as follows:
- Access the Admin Portal > Users List and click “Create New”.
- In the creation dialog, search for the O365 Display Name or UPN of the User, as specified in your Microsoft 365 Admin Center > Users section.
- Specify an Organization Unit for this new User.
- Click “Create” and wait for the process to complete.
⮑ The new User is now ready to log into the Nimbus Portal. Note that Portal Roles are granted when the User is added to a Service, either via MS-Teams (as part of the related Team), or manually in a Nimbus Contact Center Service.
☝ Knowing about Organization Units: The Organization Unit (OU) concept is essential throughout Nimbus. The OU will determine where your User is visible for selection within Nimbus configuration-related UIs, e.g. when other Service Owners want to search for and add the User to their roster.
💡 Good to know: You can change the OU of a User later at any time if necessary. Any existing references (e.g. Nimbus Service assignments) will remain intact until the User is removed (either by a Service Owner or from your Entra ID directory).
Adding User through MS Teams-based Service
After following the Service Provisioning steps you can add Nimbus directly via MS-Teams. The corresponding Users will be automatically added into Nimbus and get assigned Portal Roles automatically.
Manual User assignments
💡 Good to know: Nimbus knows multiple ways of User Assignment. As an example, you can manually create additional Nimbus Services which are not tied to an MS Teams channel. Such services can share Users across multiple departments or regions (Contact Center), or have no Users at all (e.g. IVR and rerouting Services).
Manual User assignment allows for more detailed Portal Roles
🔎 For more information refer to:
User Provisioning via Nimbus API
When adding a User via Nimbus API, there is no search possible in your Microsoft Entra ID. You need to retrieve and use O365 IDs manually, which are then sent to Nimbus. Refer to Step 3 - Using the API for instructions on how to create empty Users:
Learn more….
Nimbus API
The Nimbus Public REST API allows to manage Nimbus Users and License contingencies. This page describes the setup and usage procedures.
PRECONDITIONS
💡If you have already set up Azure and Nimbus for using the API, you can directly go to → “Available Methods" chapter.
On this page the following topics are covered:
- Check if the API was enabled on your Provisioning Tenant Settings. This feature is enabled by a Luware System Administrator.
-
Set up the Nimbus App Registration and necessary API Permissions in Azure.
As a Tenant Administrator you can perform these steps below in parallel.
Step 1 - Azure Setup
✅ Tenant Administrator: The following steps need to be done with Tenant Administrator privileges. You will grant some of the Nimbus App Permissions to be used later via the API.
Create App registration
🔎 Also see: Quickstart: Register an application with the Microsoft identity platform | Microsoft Learn
- Go to Portal.Azure.com
- In your Tenant, Create an App registration, e.g. “My Nimbus App”
- Leave the other options as they are.
Grant API Web Access Permissions
🔎 Also see: Configure an app to access a web API - Microsoft identity platform | Microsoft Learn
✅ Tenant Administrator: Note that a Nimbus App must be registered at this point.
- Go to "API Permissions"
- Request new API permission by clicking “Add a permission”.
- Search for "Luware"
- Select the entry “Luware Nimbus Login” from your Nimbus App
- Select Application Permissions
- Select the following role permissions:
- “
Provisioning.User.Create” - “
Provisioning.User.Delete” - "
Provisioning.Tenant.Read" - “
Provisioning.User.Read”
- “
- Back In API Permissions, click “Grant Admin Consent for Luware AG” → Green Checkboxes signal the successful permission grant.
Authentication
There are multiple ways to authenticate with your newly created Azure Application. The method of authentication doesn't really matter for Nimbus and depends on your Use Case and external system. We therefore only add some general recommendations and point to the Microsoft Documentation.
Public Client Application
🔎 From: Public client and confidential client applications | Microsoft Learn
Public client applications run on devices, such as desktop, browserless APIs, mobile or client-side browser apps. They can't be trusted to safely keep application secrets, so they can only access web APIs on behalf of the user. Anytime the source or compiled bytecode of a given app is transmitted anywhere it can be read, disassembled, or otherwise inspected by untrusted parties, it's a public client. As they also only support public client flows and can't hold configuration-time secrets, they can't have client secrets.
🔎 From: Public client and confidential client applications | Microsoft Learn
After determining the type of client application you're building, you can decide whether to enable the public client flow in your app registration. By default, allow public client flow in your app registration should be disabled unless you or your developer are building a public client application and using the following OAuth authorization protocol or features:
OAuth Authorization protocol/Feature Type of public client application Examples/notes Native Authentication Microsoft Entra External ID application that requires full customization of the user interface, including design elements, logo placement, and layout, ensuring a consistent and branded look. Note: Native Authentication is only available for app registrations in Microsoft Entra External ID tenants. Learn more here Device code flow Applications that run on input-constrained devices such as a smart TV, IoT device, or a printer Resource owner password credential flow Applications that handles passwords users enter directly, instead of redirecting users to Entra hosted login website and letting Entra handle user password in a secure manner. Microsoft recommends you do not use the ROPC flow. In most scenarios, more secure alternatives, such as the Authorization code flow, are available and recommended. Windows Integrated Auth Flow Desktop or mobile applications running on Windows or on a machine connected to a Windows domain (Microsoft Entra ID or Microsoft Entra joined) using Windows Integrated Auth Flow instead of Web account manager A desktop or mobile application that should be automatically signed in after the user has signed into the windows PC system with a Microsoft Entra credential
Confidential Client Application / Client Secret
🔎 From: Quickstart: Register an application with the Microsoft identity platform | Microsoft Learn
Sometimes called an application password, a client secret is a string value your app can use in place of a certificate to identify itself.
Client secrets are considered less secure than certificate credentials. Application developers sometimes use client secrets during local app development because of their ease of use. However, you should use certificate credentials for any of your applications that are running in production.
- Select your previously registered Nimbus App.
- Go to Certificates & secrets > Client secrets > New client secret.
- Add a description for your client secret.
- Select an expiration for the secret or specify a custom lifetime.
- Click Add.
-
🧠 Record the Secret's value for later use within the Nimbus API.
☝This secret value is never displayed again after you leave this page.
From: Public client and confidential client applications | Microsoft Learn
Confidential client applications run on servers, such as web apps, web API apps, or service/daemon apps. They're considered difficult to access by users or attackers, and therefore can adequately hold configuration-time secrets to assert proof of its identity. The client ID is exposed through the web browser, but the secret is passed only in the back channel and never directly exposed.
Step 2 - Configure Nimbus
✅Checklist:
🧠 For the next steps in Nimbus you will need the Application ID of your previously registered Nimbus Application.
- Log into Nimbus Admin Portal.
- Go to Tenant Administration > Provisioning Tenant Settings > “Application Permissions”.
- Click on “Add”.
-
Fill in the 🧠 Azure Application ID from → Chapter: Step 1 above.
- Define the Organization Units scope under which the Nimbus API will have access.
- Save and Close.
- Still within Admin Portal, Go to the Configuration (Admin) > Organization Units
- Open your Organization Unit Entry and note the GUID in the browser address bar as follows.
🧠 Repeat this step and note down any OU ID you wanna create users in later using the API.
Step 3 - API Authentication and Usage
Now your API should be ready to use.
💡In this example we authenticate using a Confidential Client Application using Client Credentials. Of course you can use any other means of authentication as described in → Chapter: Step 1 > Authentication above.
✅Checklist:
- 🧠You will need the Nimbus Application ID and the Secret of your App
- 🧠You also need the Organization Units ID to make API calls
- ✅ Additionally, you need the O365 IDs of the (future) users you want to provision.
- Create token using OAuth 2.0. For example, to get a token using Client Credentials, choose the following:
- Grant type: Client Credentials
-
Access token URL:
https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token1 - Client ID: 🧠 Application ID of your app
- Client Secret: 🧠 As created in your app
-
Scope:
https://admin.{geography}-{number}.luware.cloud/.default2 - Client Authentication: Send as Basic Auth header
🔎Footnotes
1 Head to your Tenant Administration and check the URL in the browser address bar. Look for the part starting with “tenantId=” tenantId=9fce70af-a632-49ca-bc0d-53db5a21c5b3
2 The endpoont URL depends on the geographical location of your Nimbus Cluster. When you log into Nimbus Admin Portal you will be redirected to the right cluster. Check the Access URL list below as a reference.
INC Nimbus Admin URLs
| Switzerland 01 | https://admin.ch-01.luware.cloud/ |
|---|---|
| Switzerland 02 | https://admin.ch-02.luware.cloud/ |
| Germany 01 | https://admin.dewe-01.luware.cloud/ |
| Germany 02 | https://admin.dewe-02.luware.cloud/ |
| United Kingdom 01 | https://admin.ukso-01.luware.cloud/ |
| Australia 01 | https://admin.aue-01.luware.cloud/ |
| West Europe 01 | https://admin.euwe-01.luware.cloud/ |
| East United States 01 | https://admin.use-01.luware.cloud/ |
✅ Make sure to configure your web proxies to allow access to these domains or whitelist the complete *.luware.cloud domain.
Available Methods / Commands
✅Before you start: API calls use the Nimbus Admin URL as endpoint. This URL depends on the geographical location of your personal Nimbus Cluster. When you log into your Nimbus Admin Portal you will be redirected to the right cluster. → See 🔎Footnotes above.
CREATE a new User
| POST Create User | https://admin.{geography}-{number}/api/public-api-next/user |
| Description |
Creates a new empty (unconfigured) Nimbus user, based on the Organization Unit and O365 ID provided from existing users on your tenant. ☝Note: Only one user can be added per transaction. |
| Notes | ✅ Precondition: You require the O365 ID of an existing User on your Tenant and the 🧠 OrganizationUnit ID from the (permitted) OU (→ Chapter: Step 2 above) |
| Body | |
| Error Codes |
|
GET Details of Existing User
| GET User Details | https://admin.{geography}-{number}/api/public-api-next/user/{userO365Id} |
||||||||||||||||
| Description |
Requests the current configuration of an existing/template user. ☝Note: Only one user can be requested per transaction. What is being returned?The following user details
|
||||||||||||||||
| Notes | ✅ Preconditions: You need to provide the O365 ID of EXISTING (Template User) in the request body. | ||||||||||||||||
| Body | |
||||||||||||||||
| Error Codes |
|
GET License Usage
| GET Get License | https://admin.{geography}-{number}/api/public-api-next/user/license-usage |
| Description |
Performs a check in available Nimbus licenses, as also reflected in the Admin UI: License Management. Returns details for all licenses:
|
| Notes | ✅ Preconditions: API Request should be based on the Tenant ID. |
| Body | |
| Error Codes |
|
COPY an existing User
| POST Copy User | https://admin.{geography}-{number}/api/public-api-next/user/copy |
||||||||||||||||
| Description |
Creates a copy of an existing user, using their Nimbus User settings as template. ☝Note: Only one user can be copied per transaction. What is being copied over?Copied over are the following tabs and their settings:
|
||||||||||||||||
| Notes |
✅ Preconditions: You require both the O365 ID of EXISTING (Template User) the NEW (copy target) user for the request body.
|
||||||||||||||||
| Body | |
||||||||||||||||
| Error Codes |
|
☝Attention: Copied Users are immediately available to Nimbus
Keep in mind that – once Nimbus “learns” about a newly added user – User State checks will be immediately performed to potentially distribute newly incoming Service tasks. Depending if your source user was a productive one, the new user – while Online in MS Teams – may immediately be considered as “selectable” by Nimbus and receive calls and tasks via MS Teams, even without Nimbus being in focus for them.
🔎 The requirements for a “selectable” Nimbus User State are:
- The (copied) new User is known to Nimbus (O365 ID), → This happens after successful API command execution.
- The New user is “Online” in MS Teams. → Note that source Distribution Service Settings apply to verify their MS Teams status.
- In Nimbus: User has a “On Duty” Responsibility Profiles set as their default. → Depending on the source user this may already be the case.
Recommended Actions:
✅ After Copying / Creating the User: Note that Nimbus will check for Nimbus User Permissions and request permissions from the User after their first Portal Login. You may need to inform the User about this step or check if the permissions have already granted “on behalf of” another Tenant Admin.
✅ UI Refresh: To see the user in Nimbus listings, a refresh of the Nimbus UI is necessary.
DELETE an existing User
| DELETE User | https://admin.{geography}-{number}/api/public-api-next/user/{userO365Id} |
| Description |
Removes a User profile from the Nimbus Admin Portal. The User is also removed as Service Agent/Service Owner from the services where applicable. ☝Notes:
|
| Notes |
✅ Preconditions:
Results:
1💡Good to know: If the user is re-added (using the exact same O365 ID) it will get all the same reporting data from before. However, any configuration data is lost and needs to be restored manually or via → COPY Existing user command. |
| Body | |
| Error Codes |
|
General API Notes & Error Handling
Notes
Rate Limit: There is a limit of 60 API operations/minute. The API will delay processing if this threshold is exceeded.
General Error Codes
If not specificed in the Command, the error codes are as follows:
- 401 - Required role missing
- 401 - No tenant id
- 401 - Invalid tenant id
- 401 - No app id
- 401 - Invalid app id
- 401 - Provisioning Api disabled by admin
- 401 - No app permission found for app id ({appid})
- 403 - No authenticated user
- 500 - Unable to check configuration
Standard Response Codes also apply. See: https://restfulapi.net/http-status-codes/
Follow-up steps
Granting Permissions
Note that - especially after a first-time Nimbus Installation - Users may need to individually log into Nimbus and grant User Permissions for allowing Nimbus to access their personal details. As a Tenant Administrator you can grant these permissions on behalf of your entire Tenant.
Managing User Details
Depending on the type of service and its configuration, your Users may already receive incoming calls or place outbound calls on behalf of the service. Once you are settled in, head over to the respective User's General User Settings to apply licenses, which enables additional Nimbus Features.
💡 Good to know: You can select multiple Users and manage many of their options at once. Learn more about this by visiting Bulk Editing Users.