API keys

An API key lets your own software read and change WorkWing data without a person logging in. Every key belongs to one brand, carries only the permissions you tick, and can be revoked the moment you stop trusting it.

Open Settings > API Keys. You need the Tenant Admin role.

The API is on every plan, Free included. What changes with the plan is how many keys you can have active at once and how fast each one may call.

Plan	Active keys	Requests a minute, per key
Free	1	60
Basic	3	120
Standard	5	600
Professional	20	2,000

The heading on the list shows how many of your keys are in use. Reach the limit and you revoke one to make room for another.

Once you have a key, see Getting started with the API and the API reference. One thing to know before you write anything: every POST, PATCH, PUT and DELETE needs an Idempotency-Key header of your own choosing, and repeating a key replays the first response instead of doing the work twice. The API reference has the details.

Creating a key

1. Click Create API Key.
2. Give it a Name you will recognise later, such as “CRM integration”. 25 characters at most.
3. Pick the Brand the key works in. It sees that brand’s data and no other.
4. Tick the Permissions the key needs, and nothing else.
5. Add an IP Whitelist if you know where your software calls from.
6. Choose an Expiration: Never, 30 days, 60 days, 90 days or 1 year.
7. Click Create API Key.

Caution

The key is shown once, on the screen that says it was created. Copy it there and store it somewhere safe. Nothing can show it to you again, so a key you did not copy has to be revoked and replaced.

A key acts as the person who created it, within the permissions you ticked. If that person’s own access is narrower than the permissions on the key, the narrower one wins.

What a key looks like

A key is two parts separated by a dot:

ww_sk_live_abc123XYZ.veryLongSecretString123

The part before the dot is a public prefix. It appears in the Key Prefix column of the list, so you can write it into your own logs and tell which key made a request. The part after the dot is the secret, and is the part to protect.

Permissions

Permissions are grouped on the form the way the API is: jobs, customers, resources, locations, scheduling, job parts, custom fields, reference data and integrations. Each one names what it lets a key do, with the string the API checks next to it, such as Read Jobs (read:jobs).

Action	What it covers
Read	Fetching one record by its id, and listing records
Create	Adding a new record
Update	Changing an existing record
Delete	Removing a record, where the API allows it
Execute	Running an integration

Write permissions include read, and the form says so. Reference data (job types, the parts catalogue, brands, skills and your organisation’s own details) is read-only. There are no permissions for managing webhooks or API keys themselves; both are managed from the web app only.

Each group also offers quick buttons that tick several permissions at once, such as Jobs (Full Access) or Customers (Read). They are a shortcut on the form; what gets stored is the individual permissions they tick.

Full Access grants everything, across every resource and action. Give a key the smallest set it can work with instead.

Note

Some endpoints need two permissions for what looks like one action. Creating a project needs Create Jobs and Read Jobs, because the endpoint reads the project back in its response and that read is checked like any other. Grant Read Jobs alongside Create Jobs on any key that creates jobs or projects.

Restricting a key by IP address

Allow all IP addresses is ticked by default. Untick it and add the addresses your software calls from, in CIDR notation such as 192.168.1.0/24 or 10.0.0.5/32. A plain address gets its range added for you. You can list 10 addresses on one key.

A request from anywhere else is refused, whatever the key’s permissions say.

Revoking a key

Open the key’s actions menu, click Revoke, and type the key’s name to confirm. You can record a reason, which shows on the revoked key so you remember why.

The next request made with that key is rejected. The same goes for a key that has expired or been deactivated.

Keeping keys tidy

The list shows when each key was last used and when it expires. Name keys after what uses them, give a temporary integration an expiry, and revoke a key the moment its job is done or you think it has been seen by someone it should not have been.