Scopes

A key can only call the endpoints its scopes allow. Give each integration the fewest scopes it needs.

How scopes work

Scopes look like int:<area>.<resource>:<read|write>, plus int:webhooks:manage.
A :write scope includes its :read: a key with int:fin.invoices:write can also list and read invoices.
You choose scopes when you create a key in Settings → API keys. A key's scopes cannot be changed afterwards — create a new key.
int:* grants every scope. It is not offered in the apps; it is needed only to subscribe to the 64 event types that have no read endpoint (compliance, e-invoicing, DATEV, tachograph, dashcam and e-signature) or to every event (["*"]) — ask support.

All scopes

Scope	Allows
`int:files.documents:read` read	GET `/v1/documents` — List documents GET `/v1/documents/{id}` — Retrieve a document
`int:fin.bills:read` read	GET `/v1/bills` — List bills GET `/v1/bills/{id}` — Retrieve a bill
`int:fin.invoices:read` read	GET `/v1/invoices` — List invoices GET `/v1/invoices/{id}` — Retrieve an invoice
`int:fin.invoices:write` write	POST `/v1/invoices` — Create a draft invoice PATCH `/v1/invoices/{id}` — Update a draft invoice POST `/v1/invoices/{id}/void` — Void an invoice
`int:fin.payments:read` read	GET `/v1/payments` — List payments GET `/v1/payments/{id}` — Retrieve a payment
`int:fin.purchase_orders:read` read	GET `/v1/purchase_orders` — List purchase orders GET `/v1/purchase_orders/{id}` — Retrieve a purchase order
`int:fm.fuel_logs:read` read	GET `/v1/fuel_logs` — List fuel logs GET `/v1/fuel_logs/{id}` — Retrieve a fuel log
`int:fm.vehicles:read` read	GET `/v1/vehicles` — List vehicles GET `/v1/vehicles/{id}` — Retrieve a vehicle
`int:fm.work_orders:read` read	GET `/v1/work_orders` — List work orders GET `/v1/work_orders/{id}` — Retrieve a work order
`int:hr.employees:read` read	GET `/v1/employees` — List employees GET `/v1/employees/{id}` — Retrieve an employee
`int:hr.leave_requests:read` read	GET `/v1/leave_requests` — List leave requests GET `/v1/leave_requests/{id}` — Retrieve a leave request
`int:hr.timesheets:read` read	GET `/v1/timesheets` — List timesheets GET `/v1/timesheets/{id}` — Retrieve a timesheet
`int:support.tickets:read` read	GET `/v1/tickets` — List tickets GET `/v1/tickets/{id}` — Retrieve a ticket
`int:webhooks:manage` manage	GET `/v1/webhook_endpoints` — List webhook endpoints POST `/v1/webhook_endpoints` — Create a webhook endpoint GET `/v1/webhook_endpoints/{id}` — Retrieve a webhook endpoint PATCH `/v1/webhook_endpoints/{id}` — Update a webhook endpoint DELETE `/v1/webhook_endpoints/{id}` — Delete a webhook endpoint POST `/v1/webhook_endpoints/{id}/rotate_secret` — Rotate the signing secret POST `/v1/webhook_endpoints/{id}/pause` — Pause a webhook endpoint POST `/v1/webhook_endpoints/{id}/resume` — Resume a webhook endpoint GET `/v1/webhook_endpoints/{id}/deliveries` — List deliveries for an endpoint POST `/v1/webhook_endpoints/{id}/deliveries/{delivery_id}/replay` — Send a delivery again POST `/v1/webhook_endpoints/{id}/deliveries/replay_failed` — Send failed deliveries again
`int:identity.users:read` webhooks only	No endpoint. Subscribing a webhook endpoint to `identity.user.created`, `identity.user.deactivated`, `identity.user.reactivated` needs it. Settings → API keys does not offer it; a key with `int:*` covers it — ask support.
`int:messaging.messages:read` webhooks only	No endpoint. Subscribing a webhook endpoint to `messaging.message.sent` needs it. Settings → API keys does not offer it; a key with `int:*` covers it — ask support.

When a scope is missing

The request is refused with 403 and the scope the key needs:

{
  "type": "https://officehero.io/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The API key does not have the scope required for this endpoint.",
  "detail_key": "errors.integrations.missing_scope",
  "missing_scope": "int:fin.invoices:write"
}

Create a key that includes missing_scope; existing keys cannot be widened.