> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zivio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> Every OAuth scope in the Zivio API and what it grants

### How scopes work

Each endpoint requires a specific scope. You choose which scopes to request when you
[exchange your credentials for a token](/v4/authentication), as a space-separated string:

```
scope="projects:read milestones:read invoices:read"
```

You are granted the intersection of what you asked for and what your OAuth client is
permitted to hold — so always read the `scope` field on the token response rather than
assuming the request was honoured in full.

Calling an endpoint without its scope returns `403` with `error: insufficient_scope`, naming
the scope required and the scopes you hold:

```json theme={null}
{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token",
  "required_scope": "projects:read",
  "provided_scopes": ["welcome:read"]
}
```

<Tip>
  Request the narrowest set that does the job. A reporting integration needs only `:read`
  scopes; nothing that merely reads data should hold a `:write` scope.
</Tip>

### Naming

Scopes follow `<resource>:<action>`, where the action is `read` or `write`. A `:write` scope
covers creating and updating that resource — it does not imply the matching `:read` scope, so
request both if you need to read what you have written.

`welcome:read` is a special case: it grants `GET /welcome`, the whoami endpoint. Include it in
every token so your integration can confirm its own identity and granted scopes.

### Available scopes

| Scope                         | Grants                                                                                              |
| ----------------------------- | --------------------------------------------------------------------------------------------------- |
| `bank_accounts:read`          | Read bank account details on suppliers and the org.                                                 |
| `bid_evaluations:read`        | Read evaluation scorecards for bids, including criterion scores and quality, cost and total scores. |
| `bid_evaluations:write`       | Score bids against a project's quality criteria and override calculated cost scores.                |
| `bids:read`                   | Read bids submitted on projects.                                                                    |
| `bids:write`                  | Shortlist, select, eliminate and reinstate bids submitted on projects.                              |
| `eoi_responses:read`          | Read responses to expressions of interest.                                                          |
| `eois:read`                   | Read expressions of interest.                                                                       |
| `invoices:read`               | Read invoices on projects.                                                                          |
| `invoices:write`              | Create and update invoices.                                                                         |
| `milestones:read`             | Read milestones on projects.                                                                        |
| `notes:read`                  | Read notes on projects and EOIs.                                                                    |
| `notes:write`                 | Create and update notes on projects and EOIs.                                                       |
| `offers:read`                 | Read offers for projects.                                                                           |
| `orgs:read`                   | Read organization records.                                                                          |
| `project_approvals:read`      | Read project approval workflows.                                                                    |
| `project_approvals:write`     | Create and update project approval workflows.                                                       |
| `project_conversations:read`  | Read messages exchanged with suppliers on a project.                                                |
| `project_conversations:write` | Send messages to suppliers on a project.                                                            |
| `project_invitations:read`    | Read supplier invitations on projects.                                                              |
| `project_invitations:write`   | Invite suppliers to bid on projects.                                                                |
| `project_questions:read`      | Read supplier clarification questions on projects.                                                  |
| `project_questions:write`     | Answer and approve supplier clarification questions.                                                |
| `projects:read`               | Read projects.                                                                                      |
| `projects:write`              | Create and update projects.                                                                         |
| `purchase_orders:read`        | Read purchase orders.                                                                               |
| `raw_scorecard_entries:read`  | Read raw scorecard entries.                                                                         |
| `reviews:read`                | Read reviews left on suppliers.                                                                     |
| `skill_taxonomies:read`       | Read skill taxonomy structure.                                                                      |
| `supplier_lists:read`         | Read curated lists of suppliers.                                                                    |
| `supplier_users:read`         | Read users belonging to supplier organizations.                                                     |
| `suppliers:read`              | Read supplier profiles.                                                                             |
| `tasks:read`                  | Read the acting user's task queue, including outstanding approvals and items to review.             |
| `tasks:write`                 | Complete and dismiss tasks in the acting user's task queue.                                         |
| `tax_types:read`              | Read configured tax types.                                                                          |
| `users:read`                  | Read user profiles.                                                                                 |
| `variation_orders:read`       | Read variation orders on projects.                                                                  |
| `welcome:read`                | Required: confirms your identity to the application.                                                |

<Note>
  The token endpoint advertises a wider catalogue than the table above. Scopes that no
  documented endpoint currently uses are omitted here — if you need one of them, contact
  [support@zivio.com](mailto:support@zivio.com) before building against it.
</Note>

### Choosing scopes

<AccordionGroup>
  <Accordion title="Reporting or data warehouse sync">
    Read-only across the resources you export, plus `welcome:read`. For example:
    `welcome:read projects:read milestones:read invoices:read suppliers:read`.
  </Accordion>

  <Accordion title="Project intake from another system">
    `welcome:read projects:write projects:read` — write to create the project, read to confirm
    the result and poll its state.
  </Accordion>

  <Accordion title="Bid evaluation workflow">
    `welcome:read projects:read bids:read bid_evaluations:read bid_evaluations:write` — add
    `bids:write` only if the integration also shortlists, selects or eliminates bids.
  </Accordion>

  <Accordion title="AI assistant via the MCP server">
    Start read-only — `welcome:read` plus the `:read` scopes for the resources you want
    queried. Add `:write` scopes only once you are comfortable with an assistant mutating
    live records. See [MCP server](/v4/mcp).
  </Accordion>
</AccordionGroup>