Configure Staff API
How to Configure the Staff API on PlaceOS
The Staff API gives PlaceOS the ability to interact with Calendar and User Resources.
To integrate room booking into your existing calendar environment you must configure Staff API.
Once you have configured Staff API, PlaceOS can:
- Delete Calendar events in Microsoft 365 or Google Workspace.
- Access on Microsoft Azure or Google Cloud Console & Workspace to create apps and API permissions
- Administrator access to your PlaceOS Backoffice
To enable Staff API you must complete the necessary configuration in your cloud provider.
Instructions for Microsoft 365 and Google Workspace are below.
To use Staff API with 365 you will need to create an Application in App Registration.
If you have already created an app, you ca skip to Grant Graph API Permissions.
If not, you will need to create a new App Registration on Azure.
- 2.Log in and select the correct Subscription for your application
- 4.Select New Registration
- 5.Enter the required information
- Name it and select the appropriate "Support Account types" (typically "Single tenant")
- Optionally paste the PlaceOS
- 6.Register the app
You will now need to grant Graph API Permissions on your App.
- 1.Select the app you would like to give permissions
- 2.Click API Permissions
- 3.Click Add Permission
- 4.Click Microsoft Graph
- 5.Select Delegated permissions
- 6.Grant API Access to the following resources (or whichever resources are approved by the Azure administrator):
- 7.Click Add Permissions
- 8.Grant Admin Consent for all the new permissions
You will now need to create the secret to allow PlaceOS Staff API to Authenticate.
- 1.Navigate to Certificates & Secrets
- 2.Select New client secret
- 3.Give your secret a description e.g.
PlaceOS Prod App Secretand click Add
- 4.Copy and Save the Secret Value (you will need this in the next step)
- 5.Return to the App Overview
- 6.Copy and Save the
Tenant ID(you will need these in the next step)
To use Google APIs you will need a server to server OAuth2 application configured.
This involves creating a service account that PlaceOS will use for authentication.
The service account can “act as” staff in the organization.
The service account can perform actions on behalf of a user, such as booking meeting rooms.
Configure Google Cloud API Project
- 2.Configure an existing API Project or Create a New API Project
- 3.Open your API Project and select
APIs & Servicesfollowed by
Enable APIs and Services
- 5.Search for and enable the following SDK:
- Admin SDK (for staff directory)
- Google Calendar API
- Google Drive API (for attachments)
- 6.For limiting access to a subset of the organization, you may also want to enable:
- Marketplace SDK (not Marketplace API)
- Drive API
- 1.Under APIs & Services, navigate to Credentials
- 2.Click on the Create Credentials and select Service Account Key
- 3.Create a new Service Account
- 4.You can ignore the next steps in the wizard, click
Doneto return to the list of service accounts
- 5.Click the service account you created and select the
Keystab to create an access key
- 6.This will save a JSON File to your computer, you will need this information to configure the service.
- 7.Once the key has saved, return to the
Detailstab and enable Domain Wide Delegation
- 8.Click Save
If you want to configure this application for use in a subset of the organization, ignore this step.
Continue with the steps to “Create a marketplace application”
- 1.Open the JSON File that we saved in the previous step
- 2.Copy the
- 5.Scroll down to
Manage Domain Wide Delegation
Add newand enter the
client_idyou extracted earlier
- 8.Add the following API Scopes:
- 10.Ensure you enable API Access by going to
Security -> API Controls
Trust internal, domain owned apps
https://www.googleapis.com/auth/drive.fileallows the application to add attachments to calendar events, such as QR codes.
It does not allow for reading or modifying any files not created by the application.
This step applies to organizations where a specific region or department (OU) will be using the application.
This step is not applicable to most organizations.
- 2.Select the G Suite or Google Workspace Marketplace SDK
- 3.Select the
- 4.Fill in the app name and description, un-check
Enable individual install
- 5.Upload icons as required
- 6.A Terms of Service URL is also required, you can set this to your companies homepage
- 7.Enter the following scope URL:
- 8.Enable drive extension and click
Configure drive SDK
- 9.Fill in the details and icons for the Drive Application
- 10.Once completed, return to the marketplace application form
- 11.Ensure you set visibility to
Deploy the marketplace application to the organizational unit that will be using the application.
You will now need to enter the information obtained from the App Registration and API Permissions.
To complete this step, you will need the following information:
- Microsoft Azure (all information obtained from Azure App Register)
- Google Workspace
Domain- this is the domain your users use when logging into Google
Service Account Email- service account user created in previous steps
Scopes- what Google services are we accessing (calendar, admin groups, etc)
Private Key- available via the JSON downloaded from Google Cloud Console
Service User- a Google Workspace user with required permissions to read resource calendars/user information
User Agent- user defined and helps with looking at Google logs to see application actions
- 1.Open PlaceOS Backoffice and login as an administrator
- 2.Navigate to the Admin Tab
- 3.Select Staff API
- 4.Select the Domain you want to configure
- 5.Click Add Tenant
- 6.Enter the information required
- 7.If you are configuring access for Microsoft 365 ensure you tick 'Delegated Access' and enter
teamsForBusinessin the Conference Type field.
staff-apilogs will show any errors in configuration.
We can view these logs by connecting to the server and running
docker logs --tail 99 -f staff-api.
An example log with an authentication error to Microsoft 365:
level=[E] time=2021-06-24T04:10:58Z program=StaffAPI source=action-controller client_ip=22.214.171.124 request_id=50173a7d-a819-4413-8f8a-94adf592f309 domain=poc.placeos.com tenant_id=71 event=error method=GET path=/api/staff/v1/calendars/free_busy?period_start=1624507858&period_end=1624543199&zone_ids=zone-HDvnRd_9lAS status=500 duration=345.62ms
error fetching token UNAUTHORIZED (401)
"error_description": "AADSTS7000215: Invalid client secret is provided.\r\nTrace ID: 6f090c0f-079f-4930-a123-b1242a4f3f00\r\nCorrelation ID: 0424faa6-2325-4c79-b0e3-726d68db7655\r\nTimestamp: 2021-06-24 04:10:58Z",
"timestamp": "2021-06-24 04:10:58Z",