The Nimbus Public REST API allows to manage Nimbus Users and License contingencies. This page describes the setup and usage procedures.

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

1. Go to Portal.Azure.com
2. In your Tenant, Create an App registration, e.g. “My Nimbus App” 
3. 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.

1. Go to "API Permissions"
2. Request new API permission by clicking “Add a permission”. 
3. Search for "Luware"
4. Select the entry “Luware Nimbus Login” from your Nimbus App
5. Select Application Permissions 
6. Select the following role permissions: 
   1. “Provisioning.User.Create”
   2. “Provisioning.User.Delete”
   3. "Provisioning.Tenant.Read" 
   4. “Provisioning.User.Read”
7. 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.

Step 2 - Configure Nimbus

1. Log into Nimbus Admin Portal.
2. Go to Tenant Administration  > Provisioning Tenant Settings > “Application Permissions”.
3. Click on “Add”. 
4. Fill in the 🧠 Azure Application ID from → Chapter: Step 1 above.
   
5. Define the Organization Units scope under which the Nimbus API will have access. 
6. Save and Close. 
7. Still within Admin Portal, Go to the Configuration (Admin) > Organization Units
8. 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.

1. Create token using OAuth 2.0. For example, to get a token using Client Credentials, choose the following:
2. Grant type: Client Credentials
3. Access token URL: https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token¹
4. Client ID: 🧠 Application ID of your app
5. Client Secret: 🧠 As created in your app
6. Scope: https://admin.{geography}-{number}.luware.cloud/.default²
7. Client Authentication: Send as Basic Auth header

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

{
 "o365Id": "<guid>",
 "organizationUnitId": "<guid>"
}

GET Details of Existing User

Empty Body

GET License Usage

Empty Body

COPY an existing User

{
 "newO365Id": "<guid>",
 "sourceO365Id": "<guid>"
}

DELETE an existing User

{
 "o365Id": "<guid>",
}

General API Notes & Error Handling