Keys and roles
An API key lets another system work in your Workscope company without anyone's password.
Sending the key
Put it in the Authorization header of every request, after the word Bearer:
Authorization: Bearer wsk_your_key_hereKeys are only ever sent over HTTPS. Never put one in a web page, an app, or anywhere a customer could see it. Treat it like a password.
Roles
Each key acts with a role, chosen when you make it. It follows the same rules as a person with that role.
| Role | What it can do |
|---|---|
| Owner | Everything a key can do (see below for the few things it can't). Only an owner can make an owner key. |
| Admin | Run the day-to-day: clients, projects, bookings, the team, timesheets, holiday, invoices and the rest. |
Either role can also be made read only: it can look at everything its role allows, but any request that would change something is refused with 403 and the code ReadOnlyKey. Good for reports and accounts systems.
A key can also be kept from parts of Workscope (modules), just like a login. To that key, those parts behave as if they were switched off.
Each request in the reference shows the permission it needs and, where it belongs to one, the module that must be switched on.
What keys can't do
Some things stay with people, whoever holds the key:
- Signing up, logging in and out, and sign-in links.
- Changing anyone's password or email address.
- Inviting logins, changing their roles, or removing them.
- Making, changing or stopping API keys.
- Closing the company.
Keeping keys safe
- Use one key per system, so you can switch one off without touching the others.
- Give each key the smallest role that does the job.
- Settings › API keys shows when each key was last used. Stop keys you no longer need.
- If a key may have leaked, stop it straight away. It stops working at once, for good.
Changes made with a key
Wherever Workscope shows who did something, a change made with a key shows the key's name, such as "API key: Accounts sync".