Introduction
Workspace One UEM provides a collection of APIs that allow IT infrastructures and third-party applications to use product functionalities. Leveraging REST-based APIs provide several benefits to enterprises, including eliminated cost and time spent developing applications in-house.This post is to show how you can authenticate and access Workspace One APIs.
Audience
This post is most appropriate for the following audiences:
- Anyone new to VMware Workspace One.
- Anyone new to VMware Workspace One REST APIs.
- Anyone with basic PowerShell expertise.
About Workspace One API
Workspace ONE UEM API supports multiple types of authentications. The authentication credentials are sent in the "Authorization" API request header.
- Basic Authentication.
- Certificate Authentication.
- OAuth Authentication (Recommended).
To access detailed API documentation, navigate to the Workspace One UEM API help page, like the following:
- https://[your_console_domain]/api/help
To find your REST API URL navigate to System Settings like the following:
API Key
All types of API authentication require an additional API key generated by an administrator to be sent with the request. This key is sent as “aw-tenant-code” in request header.
To get Workspace One API Key follow the next step:
- Go to system settings
You can create a new API key or copy an existing one.
Basic Authentication
This type of authentication requires Base64 encoded Username and Password of an admin account created on Workspace One console with API access.
The following is how to create basic authorization header using PowerShell:
Once done you can use authorization and API key in the request header to perform an API action. The header structure will be like the following:
Certificate Authentication
This type of authentication provides API access using a self-signed certificate generated for Admin users of the Workspace One Admin console.
Certificate authentication support two types of authentication schemes:
- CMS: Request message content should be signed with client certificate using PKCS9 singing.
- CMSURL: Request canonical URI resource encoded using UTF-8 format and signed with client certificate using PKCS9 singing.
The authentication scheme should be part of authorization header. Also, the format of the authorization header is as follow:
Authorization: CMSURL’<Version> <CREDENTIALS>
- <Version>: information, usually 1.
- <CREDENTIALS>: is the Base64 Encoded data of “canonical URI resource encoded using UTF-8 format” signed with client certificate using PKCS9 signing.
In this tutorial we will use CMSURL scheme.
Generate admin client certificate
- Log in to the Workspace One UEM Console and go to admin edit mode.
- When the edit modal is open, click on API tab
- Now export the client certificate
Create authorization header using CMSURL scheme
The following is the PowerShell code to generate the authorization header
Once done you can use authorization and API key in the request header to perform an API action. The header structure will be like the following:
OAuth Authentication
This type of authentication is the recommended form of authentication.
It requires a Bearer Token in the authorization header to authenticate to the API, but to generate a Token you will need a Client ID and a Client Secret.
- Go to OAuth Client Management in Workspace One
- Register a new OAuth client
After saving the client, copy Client ID and Client Secret and save them in a safe place because once you close the modal you cannot retrieve Client Secret again.
-
Get access token
Access token URL depends on your Workspace One region,Click Here to access a VMware article that lists all access token URLs.
We will perform the request to get access token using PowerShell:
Once done you can use authorization and API key in the request header to perform an API action. The header structure will be like the following:
Full source codes with execution of an API request are in the following GitHub Repository.
Conclusion
If you can choose between these types of authentication for your production applications that leverage Workspace One APIs, it is recommended to use OAuth authentication method.
Follow us for more articles on how to use Workspace One APIs with your in-house applications.
