Permissions
At the end of this guide you know what each permission allows, why a connection can hold fewer than you asked for, and what is never available.
The permissions
Permissions are OAuth scopes. The business owner sees them as two columns on the consent screen: View, and Add or change.
| Permission | Shown to the business as | Allows |
|---|---|---|
| roster:read | View rosters and shifts | Rosters, shifts, availability, open-shift requests, shift swaps, who can cover a shift, and rostered hours in labour costs. |
| roster:write | Add or change shifts that haven't started | Create shifts as drafts, and change or delete shifts that have not started. A change to a published shift makes it a draft again. |
| ondemand:read | View OnDemand shifts | OnDemand shifts and their status, with nothing about the worker. The hourly rate needs pay:read too. |
| ondemand:write | Add or change OnDemand drafts | Create draft OnDemand shifts, and change or delete drafts. The venue sets the rate and publishes in Shiftly. |
| timesheets:read | View timesheets | Timesheets, who's on now, timesheet totals and actual hours in labour costs, without pay fields. |
| timesheets:write | Add or change pending timesheets | Create, change and delete pending timesheets. |
| leave:read | View leave and balances | Leave requests, balances, blackout periods and the business's leave types. Private kinds of leave show only as PRIVATE. |
| leave:write | Add or change pending leave requests | Submit, change and cancel pending leave requests. |
| people:read | View staff details | Employees and employments, including dates of birth and addresses. |
| pay:read | View pay and labour cost | Pay fields on employments, shifts and timesheets, cost in totals and labour costs, and project budgets. |
| settings:read | View business details and locations | The business, its locations and positions, and each location's labour cost target. |
| payrules:read | View awards and pay rules | Awards. |
| projects:write | Add or change projects | Create, rename and archive projects. |
| offline_access | Stay connected without the person signing in again | A refresh token. |
Ask for what your product needs and no more. The business sees every permission you request, and a shorter list is easier to allow.
A connection does no more than the person who made it
Every request your app makes runs as the person who connected it, inside the business they connected. If a manager without access to pay connects your app, your app does not see pay either, even with pay:read granted. If that manager can only see one location, your app sees that location.
On the consent screen, a permission the person cannot share is shown as unavailable and left out of the grant. The scope in the token response tells you what you actually hold.
Reduced access
When the person who connected your app later loses a permission, your app loses it too. Requests needing it answer 403 permission_denied and name the permission. The business sees the connection as Reduced access on its Connected apps page, with the option to restore the person's access or have someone else reconnect. Your access to everything else continues.
The connection resource reports both lists: granted_permissions is what the business allowed, effective_permissions is what works right now.
GET/v1/connection
Why pay is separate
Pay is the most sensitive thing in a roster. It has its own permission so a business can share rosters and timesheets with a product that has no need to know what anyone earns. With pay:read, employments carry rates and shifts and timesheets carry cost; without it, those fields are left out.
What is never available
- Tax file numbers, bank details, superannuation details and identity documents.
- Sign-in details, passwords and PINs.
- Other businesses the person manages, or anything outside the connected business.
- Publishing rosters, approving timesheets, deciding leave, changing staff details or changing pay. These stay with the business.
- Publishing or pricing OnDemand shifts, and anything about the worker who takes one.
- Private kinds of leave, such as family and domestic violence leave, and clock-in photos. A timesheet says only whether a photo was taken.