Acting on behalf of users
Send v2 requests as another user with the X-On-Behalf-Of header.
By default, every request made with a key acts as the key owner. To act as another user, for example to create a leave request for an employee from an HR tool, send their user ID in the X-On-Behalf-Of header:
curl -X POST https://api.vacationtracker.io/v2/leaves \
-H "Authorization: Bearer vt_live_..." \
-H "X-On-Behalf-Of: <userId>" \
-H "Content-Type: application/json" \
-d '{ "leaveTypeId": "...", "startDate": "2026-10-05", "endDate": "2026-10-09" }'The change is then made as that user: the same rules apply as when they use Vacation Tracker themselves.
Requirements
- The key needs the
users:act-on-behalfscope. It is a sensitive action, so it is never enabled by default. See Scopes. - The target user must be someone the key owner manages:
| Key owner | Can act on behalf of |
|---|---|
| Administrator | Anyone in the workspace |
| Location admin | Users in the locations they manage |
| Approver | Users in the departments they approve |
| User | Nobody (only themselves) |
Sending the key owner's own ID, or omitting the header, acts as the owner. An empty header is rejected with VALIDATION_ERROR.
The intersection rule
A request on behalf of a user is allowed only if both sides may do it:
- The key, and therefore its owner, has the scopes the request needs.
- The target user's own role allows the same scopes.
Example
An administrator's key has leaves:approve and users:act-on-behalf. Using it to approve a leave on behalf of an employee fails, because an employee cannot approve leaves. The key cannot give the employee more power than they have, and the employee cannot borrow the administrator's power.
Errors
| Code | Status | When |
|---|---|---|
INSUFFICIENT_SCOPE | 403 | The key does not have users:act-on-behalf, or a scope the request needs. |
ON_BEHALF_OF_NOT_ALLOWED | 403 | The target user is outside what the key owner manages (details.reason is TARGET_OUTSIDE_REACH), or the target's role does not allow the request (details.reason is TARGET_NOT_PERMITTED, with details.missingScopes). |
RESOURCE_NOT_FOUND | 404 | No user with this ID exists in the workspace. |
VALIDATION_ERROR | 400 | X-On-Behalf-Of is present but empty. |
See Errors for the full catalog.
What the audit trail shows
- Everyone sees the target user as the one who made the change, followed by the integration name when the key has one: "Marcus Rodriguez (through HR_BOT)". This appears in the leave timeline, notifications and company logs.
- Company logs also show the key owner, so administrators can trace every change back to the key and the person responsible for it.
- The key's activity in the dashboard lists each write request with the user it acted as.