Tokens and scopes
A personal access token lets an agent read VendOrca as you. You choose what it may read and when it expires, and you can revoke it at any time.
On this page
Issue a token
Agent access must be On for your workspace. A Program Admin turns it on once; see the quickstart. Then:
- Open Agent access from the nav rail. In the supplier portal, Billing Entity users find the same page under Agent access in the portal nav.
- Read the disclosure above the form.
- Fill in the form and select Issue token.
| Field | What to enter |
|---|---|
| Name this token | Required, up to 120 characters. Pick something you will recognize in your list, for example Claude Desktop on my laptop. |
| What may it read? | One or more of Program, Workforce, Financial and Personal data. See Scopes. |
| Expires after (days) | From 1 to 365. The default is 90. |
| Acknowledgement | Select I have read the above and I am issuing this token in my own name. |
You can only issue tokens for yourself. The form has no field for another user, including for Program Admins. A Worker or Billing Entity sign-in must be linked to its worker or supplier record first. Until then, the page shows a notice instead of the form, and the person asks their Program Admin to arrange the link.
Token format
The new token appears once, under Your new token, with the notice Copy this token now. It is not shown again. It has three parts separated by dots:
vo_agt.<prefix>.<secret>For example, vo_agt.XXXXXXXX.XXXXXXXXXXXXXXXX…. The prefix is not secret. Your token list shows it so you can tell tokens apart. The whole value is a credential. Store it like a password, and send it only in the Authorization: Bearer header, never in a URL or query string.
Expiry
Every token expires. The default is 90 days and the maximum is 365. VendOrca computes the expiry date in UTC. After it passes, the token returns 401 unauthorized, and you issue a new one.
Your tokens list
Your tokens on the Agent access page lists only the tokens you issued. Each row shows the name, the prefix, the issue and expiry dates, and the scopes. A token that can read personal data carries a Reads personal data badge. Revoked and expired tokens show a Revoked or Expired badge.
Revoke a token
Find the token under Your tokens and select its Revoke <token name> button. Revocation takes effect on the token's next request. From then on it returns 401 unauthorized, the same response as an expired token.
You can revoke only your own tokens. If your account is deactivated, your tokens stop working too.
Scopes
A token can carry four scopes. Each operation needs exactly one of the first three. The fourth, read:pii, unlocks no operation of its own. It adds personal fields to results you can already read.
| Scope | Form label | Operations it unlocks |
|---|---|---|
| read:workforce | Workforce | Worker profiles (list_workers, get_worker) and timesheets with their time entries (list_timesheets, get_timesheet). Time is in minutes or units, with no money. |
| read:program | Program | Suppliers (list_suppliers, get_supplier), approval statuses (list_approval_statuses), the report catalog (list_catalog) and the list of saved queries (list_saved_queries). |
| read:financial | Financial | Assignments with their rates (list_assignments, get_assignment), expenses (list_expenses, get_expense), invoices (list_invoices, get_invoice), program configuration including rate cards (read_program_config), and report queries (run_semantic_query, run_saved_query). |
| read:pii | Personal data | No operations. Adds a worker's displayName and workEmail, and a supplier's billingEmail, to results. Without it, those fields are omitted from the response. |
The hints next to each checkbox on the form are short summaries. This table is the exact list. Assignments and program configuration need Financial because they carry rates. Supplier organization names are business data, so they are returned with or without read:pii.
How your role and scopes combine
A token can do something only when both of these allow it:
- The token carries the scope for the operation.
- Your own account can open the matching page in the app and see those records.
Your effective access is the overlap of the two. A scope never widens what your role can see. VendOrca checks both on every request, so if your role changes, your tokens change with it on their next request.
| Operations | Who can use them |
|---|---|
| Workers, assignments, timesheets, expenses | Staff roles, across the workspace. A Worker sees only their own records. |
| Suppliers, invoices | Staff roles, across the workspace. A Billing Entity sees only its own records. |
| Approval statuses, program configuration, reports | Staff roles only. |
Staff roles are Program Admin, Hiring Manager, Finance / AP, HR / Compliance and Executive. See Roles and permissions.
What a token can never do
Every operation is read-only. No scope exists, now or on any plan, that lets an agent:
- approve anything for payment;
- see the credentials of connected systems;
- grant or change roles;
- invite, remove or deactivate users;
- change your VendOrca subscription or billing;
- run raw SQL;
- apply or change program configuration;
- issue, list or revoke tokens, or turn agent access on or off.
People do these things in the app, signed in as themselves.