ProvisionPoint API & Setup

Title

URL Name

ProvisionPoint-API

Question

Answer

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
1. Enter a relevant name for the application
2. Ensure that "Accounts in this organizational directory only" is selected for supported account types.
3. 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
1. Click "New client secret" to open the dialogue to create.
  This will be used in your connections to the ProvisionPoint API to authenticate.
  1. Provide a description
  2. 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
1. Open the Group
2. Click + Add Members
3. Search for the App Id or API App registration name to find the correct service principal
4. 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.
1. Click + Add Access
2. Type the name of the Security Group created in the previous step
3. 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
1. 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:

Location	ProvisionPoint UI Instance	API URL
UK	https://app.provisonpoint.com	https://api.provisionpoint.com/v1.0
US	https://006.us-pp365.app	https://006api.us-pp365.app/v1.0
EU	https://009.eu-pp365.app	https://009api.eu-pp365.app/v1.0
AU	https://011.au-pp365.app	https://011api.au-pp365/v1.0
CH	https://016.ch-pp365.app	https://016api.ch-pp365.app/v1.0

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	/service-instances	Provide all the metadata that is mandatory for a request.
Import Workspaces	/service-instances	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