What can the API do?
ProvisionPoint has a RESTful API that can be used to complete a variety of tasks, these include:
- Import existing Teams, Sites or Viva Communities
- Create new workspaces from a Service Definition template
- Get existing workspace information
- Check a job* status
- Change approvers on pending approvals
- Change the associated Service Definition to a workspace
- Run Actions**
*A job is a creation, Action or approval request, all are processed through the job queue
**Not all Actions are available at this time and some require additional configuration.
Connecting to the API
To work with our API we recommend configuring an AAD App Registration that will authenticate your access, then make sure the API App registration has the authorisation to complete the tasks held within.
All the instructions to configure the app registration are available below:
1. Create an App Registration in Entra Admin Centre
If you have an existing App registration already created this can be amended to include the redirect and API permissions.
- Login to Azure Active Directory with an account with appropriate permissions to create App registrations.
-
Go to App Registrations and click "New registration".
-
Complete the new registration form
-
Enter a relevant name for the application
- Ensure that "Accounts in this organizational directory only" is selected for supported account types.
- In the redirect URI, select the option "Public client/native (mobile & desktop)" and enter https://ppapiclient/
- Click 'Register' to create the application
The application will be created and you should be diverted to the Overview, if not from Azure Active Directory click App Registrations and double click the name of the registration you created.
Make a note of the Application (Client) ID and the Directory (tenant) ID, these will be needed later.
2. Add the ProvisionPoint API Permissions
- Go to API permissions and click "Add a permission".
- Select 'APIs my organization uses' and type ProvisionPoint in the search box.
- Select the delegated permission 'Access to ProvisionPoint' and click the Add permissions button.
- Once returning to the API permissions screen, click "Grant admin consent for....".
- Once completed a success message will be displayed.
Accordion summary…
Accordion body…
3. Configure Authentication (Secrets or Certificates)
- Go to Certificates & secrets.
- Upload a Certificate or Add a Secret
- Click "New client secret" to open the dialogue to create.
This will be used in your connections to the ProvisionPoint API to authenticate.
- Provide a description
- Define when you want the client secret to expire.
- Make a note of the Secret value, this will be needed later and will disappear once you leave this page.
- Make a note of the expiry date as this will need a process to apply a new secret to keep your API connections working.
4. Add the App Registration (Service Principal) to a Security Group
A Security Group in Entra is required to add the App Registration as a service principal member of the Group. This will be used to grant access to ProvisionPoint.
You can use your existing ProvisionPoint Admin Group or create a new ProvisionPoint API group.
- Go to Entra Identity Admin Centre > Groups
- Open the Group
- Click + Add Members
- Search for the App Id or API App registration name to find the correct service principal
- Add the newly created API registration to the group
5. Add the API Security Group to ProvisionPoint
Ensure the API has permission to access ProvisionPoint and perform the task of the API endpoint.
- Go to Admin > Settings > App Settings > App Managers to grant the Group access to the app if it is not already granted access.
- Click + Add Access
- Type the name of the Security Group created in the previous step
- Click OK
- To allow the API to Import or Bulk Create, add the Group to the requestors Tab for each Service Definition
- To allow the API to make changes using actions, add the Group to each action > Permissions tab as a named user or Group
- Click Save on the right hand side below each action
- Save the Service Definition
Please complete the steps above. Once the App registration is configured, ensure that you have a copy of the following:
- Client ID,
- Tenant ID
- Client Secret or certificate Thumbprint
You can connect to the API using any of the following, click the links to read more about connecting using these methods:
- PowerShell - Create a way to authenticate using the App Registration or using a user account
- PowerAutomate (Flow) - Use OAuth authentication on HTTP calls
- REST API application - Setup the connection using the Oauth options and collections to run requests
API Endpoints
Each task that can be run through the API have unique endpoints, this is made up of a base URL and the unique endpoint for the task.
The Base URL is made up of the API instance for ProvisionPoint and the version. They are listed in the table below:
The rest of the endpoint will determine what you will be doing in the tasks and in some cases which workspace will be affected. The table below lists the rest of the URI and any additional information you will need:
|
Task
|
Endpoint
|
Additional information required
|
|
Create Workspaces
|
| Provide all the metadata that is mandatory for a request. |
|
Import Workspaces
|
| Provide all the metadata that is mandatory for a request same as for create, but also add:
- Import=$true
- ImportLevel=1, 2 or 3
- 1 = Import only & use Lifecycle and Actions
- 2 = Import, lifecycle, actions & Integration
- 3 = Import and apply additional elements (excludes Security options)
- ImportIdentifier=$AbsoluteUrl (this is how we find duplicates use the SiteUrl
- ImportStartLeaseFromInstanceCreation = $false or $true
- true will set the requested date to the date it was created in M365.
- false will set it to the date it was imported
|
|
Get existing workspaces Information
|
- /service-instances
- /service-instances?filterField1=[addfield]&filterValue1=[add value]&filterOp1=eq
- /service-instances/[ServiceInstanceId]
|
- Filter details, if using the filter functionality
- To look for a specific workspace information the ServiceInstanceId will be required.
|
|
Check or manage the Job Queue
|
- /execution
- /execution/[operationId]
- /execution/paused
- /execution/awaiting-approval
- /execution/failed
- /execution/processing
- /execution/[operationId]/continue
- /execution/[operationId]/cancel
- /execution/[operationId]/retry
|
- OperationId of the job is required to highlight specific records
- GET methods will find workspaces including any
- paused by pre web hooks
- pending approval
- in a failed state
- in processing state
- DELETE method will allow you to remove items from the Job Queue
- Items that cannot be replayed
- Rejected approvals
- Old compliance Checks
- Can only be used if the delete button is displayed in Job Queue
- POST Method will allow you to
- Replay items
- Cancel items that are paused
- Un-pause items
|
|
Change approver
|
- /execution/awaiting-approval
- /execution/[operationId]/approval
- /execution/[operationId]/approval/tasks/[TaskId]/assignments
|
- OperationId of the job is required
- TaskID of the approval item
- GET Method to collect the current approval
- PUT method to update the approver
|
|
Change Service Definition
|
- /service-instances/[ServiceInstanceId]/service-definition
|
- ServiceInstanceId of each item to move
|
|
Run Actions
|
- /service-instances/[ServiceInstanceId]/actions
|
- ServiceInstanceId of each item to run the action on
- ActionTypeId is the ID for each action
- customActionId is the Id for any Custom Actions created
- POST Method will run the actions
|
|
Blocked Words - Add/Delete words to the app and to a blocked word template
|
- /word-templates/blocked-words
- /word-templates/blocked-words/[id]
- /words
- /words/[id]
|
- Id of the blocked word template
- Id f the Word to be used
- GET methods can collect what is currently stored
- POST method to update the blocked word template or list of words
- DELETE to remove a word or blocked word template
|