Compute scopes and roles
Which of the six work-key scopes your task needs, and how portal roles and grants differ from owning the account.
You choose a grant for the action you need. A scope limits what a key may request, while a portal role limits what a person may do. Both still depend on the current account grant and policy; a job title is not a grant.
Match a scope to the permitted action
A work key can receive a subset of these six scopes. Check its actual permissions; no key needs every scope for every task.
| Scope | Requests covered | Boundary |
|---|---|---|
jobs:read | Read jobs, batches, events, results, capabilities and receipts | Result decryption and delivery require their own permission. |
jobs:write | Submit a job or request cancellation | A job still needs valid admission and spend authority. Cancellation is not proof that execution has stopped. |
batches:write | Submit a batch | Does not raise limits or approve work outside that batch. |
quotes:read | Create quotes and read pricing | A quote is not approval to run. |
models:write | Prepare and complete artifacts | Does not authorize arbitrary model training or storage administration. |
usage:read | Read usage records | Does not authorize invoice payment or finance administration. |
The key policy excludes account, team, approval, billing, finance, limit, referral and webhook administration scopes from work-key issuance. A scope mentioned in an API description is not automatically available on your key. Adding its name to a request does not grant it.
Portal roles and explicit grants
The portal checks the role and the current grant for each action. The table describes those permission limits; it does not promise that every management control is available.
| Role | Permitted duties when the required grant is present | Important restriction |
|---|---|---|
owner | Account, work, key, team and billing duties | Ownership alone does not approve work, delivery or payment. |
admin | Work, non-owner team grants, personal keys, usage and delegated spend duties | No ownership transfer, account closure or organization-key management through the current grant matrix. |
developer | Job and batch submission | The current grant matrix does not provide cancellation or key-management grants. |
billing | Usage, invoices and billing-profile duties | No job submission or team administration. |
viewer | Account and basic metadata reads | No work submission or access changes. |
Every role, including the owner, needs a separate data-profile check for result content. Portal jobs.run and work-key jobs:write are different grants; neither issues the other.
An administrator's delegated spend duties may cover member limits, key limits and approval policy, but they do not include changing the organization's total budget. A billing label does not authorize a payment.
Match a refusal to its cause
If you are an approved customer, start in the intended account. Before requesting more access, check the person's active membership or the client's key summary. Keep the actual person or service using a key separate from the account owner.
For a rejected credential, check its expiry, revocation and how the client loads it. For a denied action, compare it with the required grant. Do not share an owner's key or change the account reference to bypass the refusal.
If a control is absent, ask the account administrator to resolve the specific task and grant rather than calling an undocumented endpoint. Share only the safe key prefix, requested action and error description, never the secret.