Authentication and keys
Every request carries an API key. A key belongs to one workspace, has its own scopes, and is named in the workspace’s Activity log on every change it makes.
curl https://api.useworkloom.com/api/public/v1/ \
-H "Authorization: Bearer $WORKLOOM_KEY"
# or
curl https://api.useworkloom.com/api/public/v1/ \
-H "X-API-Key: $WORKLOOM_KEY"Who a key acts for
| Topic | API key | Service account |
|---|---|---|
| Acts as | The whole workspace when an admin makes it. Anyone else’s key acts for them, and sees only what they see. | Its own role, like a teammate with that role. |
| Named in the Activity log as | The key’s name, as an API key. | The service account’s name. |
| Records it creates | Unowned for a workspace key, or owned by the person it acts for. | Owned by the service account. |
| When someone leaves | A key that acts for a person stops when their seat is suspended. A workspace key keeps working. | Keeps working until an admin turns it off. |
| Who can make one | Anyone whose role includes API keys. Admins have it. | Anyone whose role includes service accounts. Admins have it. |
| Rotating | Make a new key, move to it, then revoke the old one. | Rotate key: the old key keeps working for 24 hours. |
Use a service account for an integration in production: its role limits what it reaches, and it does not depend on one person’s seat.
Live and test keys
Keys start with wl_live_ or wl_test_. You choose when you make the key.
A test key reads the same records a live key with the same scopes reads, and changes nothing. Every write runs the same checks and answers with what would have happened, livemode: false, and an id of null when it would have created something. Because nothing is saved, nothing a test key does sends a webhook. The Workloom-Mode header on every response says which kind of key made it.
Make a key
- In Workloom, open Settings › API and webhooks and choose New key.
- Say what it is for, for example Warehouse sync. The Activity log shows that name.
- Choose live or test, and the scopes it needs. Give it only what it needs.
- Enter your two-step verification code.
- Copy the key. It is shown once: Workloom keeps only a hash of it.
Make a service account
- Open Settings › API and webhooks, and under Service accounts choose Add service account.
- Name it after what it does, pick its role and its scopes, and set a date to rotate the key by if you want a reminder.
- Copy the key. It is shown once.
Rotate a service account’s key
Choose Rotate key. The new key works straight away and the old one keeps working for 24 hours, so you can deploy the new one without downtime.
Revoke a key
Revoking works at once: the next call with that key gets 401 with code invalid_key. A revoked key is kept, never deleted, so the Activity log still names it.
Never put a key in browser or mobile app code, where anyone can read it. Call the API from your server.