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:

  • Create

  • Edit

  • Update

  • Delete Calendar events in Microsoft 365 or Google Workspace.

To show room status on floor maps, the PlaceOS Calendar driver must also be configured.

To enable room bookings, the PlaceOS Bookings driver must be also configured.


  • Access on Microsoft Azure or Google Cloud Console & Workspace to create apps and API permissions

  • Administrator access to your PlaceOS Backoffice

Configure Providers

To enable Staff API you must complete the necessary configuration in your cloud provider.

Instructions for Microsoft 365 and Google Workspace are below.

Microsoft Azure (365)

To use Staff API with 365 you will need to create an Application in App Registration.

You may have already completed this step if you have configured PlaceOS for Microsoft 365 User Authentication.

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.

Create Azure App

  1. Navigate to the Azure Portal

  2. Log in and select the correct Subscription for your application

  3. Navigate to App Registrations

  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 Assertion URL

  6. Register the app

Grant Graph API Permissions

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):

    • openid

    • offline_access

    • Calendars.ReadWrite

    • Calendars.ReadWrite.Shared

    • Group.Read.All

    • User.Read

    • User.Read.All

    • Contacts.Read

    • Place.Read.All

  7. Click Add Permissions

  8. Grant Admin Consent for all the new permissions

Generate Azure API Secret

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 Secret and click Add

  4. Return to the App Overview

Google Workspace

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.

For further information see Creating and Managing Service Accounts.

Configure Google Cloud API Project

  1. Select Enable APIs and Services

  2. Search for and enable the following SDK:

    • Admin SDK (for staff directory)

    • Google Calendar API

    • Google Drive API (for attachments)

  3. For limiting access to a subset of the organization, you may also want to enable:

    • Marketplace SDK (not Marketplace API)

    • Drive API

Configure the Service Account

  1. Under APIs & Services, navigate to Credentials

  2. Create a new Service Account

  3. You can ignore the next steps in the wizard, click Done to return to the list of service accounts

  4. This will save a JSON File to your computer, you will need this information to configure the service.

  5. Click Save

Configure Service Account Permissions

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 client_id

  3. Select Security

  4. Scroll down to API Controls

  5. Select Manage Domain Wide Delegation

  6. Click Add new and enter the client_id you extracted earlier

  7. Add the following API Scopes:



  8. Click Authorize

  9. Ensure you enable API Access by going to Security -> API Controls

  10. Select Trust internal, domain owned apps

The scope allows 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.

Creating a Marketplace 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.

  1. On Google Cloud Console navigate to the API Services Dashboard

  2. Select the Configuration tab

  3. Upload icons as required

  4. A Terms of Service URL is also required, you can set this to your companies homepage

  5. Enter the following scope URL:




  6. Fill in the details and icons for the Drive Application

  7. Once completed, return to the marketplace application form

  8. Ensure you set visibility to My Domain

  9. Click Save Changes

Deploy the marketplace application to the organizational unit that will be using the application.

Follow the steps to Install a Google Workspace Marketplace App in your Domain.

Configure Staff API on PlaceOS

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)

    • Client ID

    • Tenant ID

    • Secret

  • 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. Save

Test Staff API Configuration

The easiest way to test the Staff API Configuration is using the PlaceOS Calendar Driver or Microsoft API Calendar Driver for 365 Delegation.

The staff-api logs 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= request_id=50173a7d-a819-4413-8f8a-94adf592f309 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": "invalid_client",
    "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",
    "error_codes": [
    "timestamp": "2021-06-24 04:10:58Z",
    "trace_id": "6f090c0f-079f-4930-a123-b1242a4f3f00",
    "correlation_id": "0424faa6-2325-4c79-b0e3-726d68db7655",
    "error_uri": ""

Last updated