What a scope is
Your key is granted a specific set of scopes, and those decide which endpoints it can call. Calling one you were not granted returns 403 insufficient_scope — a valid key, refused. Scopes are never widened silently or temporarily; a wider grant means a new key.
Scopes are least-privilege on purpose. If your integration only reconciles a headcount, ask for employees:read and nothing else: a key that can read salary is a key that can leak salary.
Every scope, and what it opens
contractor:read(heightened sensitivity) — Contractor payments over a bounded processed-on window. Opens:GET /v1/contractor/payments.custom_fields:read(heightened sensitivity) — Adds acustom_fieldsarray to employee and payroll-line responses. It is additive: it opens no endpoint of its own, so a key holding only this scope can call nothing. Ask for it alongsideemployees:readorpayroll:read_detail. Opens no endpoint on its own.employees:read— The employee directory and single-employee lookups. Opens:GET /v1/employees,GET /v1/employees/{emp_id}.entities:read— Your legal entities. Opens:GET /v1/entities.leave:read— Per-employee, per-policy leave balances. Opens:GET /v1/leave/balances.masters:read— Reference data: departments, designations, work locations and the salary-component catalogue. Opens:GET /v1/departments,GET /v1/designations,GET /v1/locations,GET /v1/salary-components.payout_details:read(heightened sensitivity) — Full, unmasked bank account numbers and IFSC codes. This is the most sensitive scope in this API and is never part of a default grant. Opens:GET /v1/bank_details.payroll:read— Payroll run summaries — totals only, no per-employee lines. Opens:GET /v1/payroll/runs.payroll:read_detail(heightened sensitivity) — Per-employee pay lines inside a payroll run. Opens:GET /v1/payroll/runs/{subtotal_id}.salary:read(heightened sensitivity) — Contracted salary structures, itemised by component. Opens:GET /v1/employees/{asan_empcode}/salary,GET /v1/salary.
The heightened-sensitivity ones
The scopes marked above expose compensation, per-person pay, tenant-defined custom fields, or bank details. They are granted deliberately rather than bundled into a general read key, and Asanify will ask what the integration does with the data before granting one.
payout_details:read is stricter again. It returns full, unmasked account numbers — the destination for a real transfer, not just personal data — so it is never part of a default grant and every grant is signed off individually.
How to ask for a scope
Contact Asanify — your account manager or support — and say which scope you need and what the integration does with it. It is not a self-service switch today, and it is not something support can widen on an existing key: you get a new key with the new scope set, and you retire the old one.
Checking what you already hold
There is no endpoint that reports your own scopes. The practical test is to call one endpoint per scope and see which return 403 — the endpoint list above tells you which call proves which scope. Your Asanify contact can also confirm what a key was issued with.