Scopes

How scopes work

Each endpoint requires a specific scope. You choose which scopes to request when you exchange your credentials for a token, 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:

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

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.

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.

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 before building against it.

Choosing scopes

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.

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.

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.

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.

Get started

Authentication

Using the API

MCP server

Webhooks

Migration

How scopes work

Naming

Available scopes

Choosing scopes

​How scopes work

​Naming

​Available scopes

​Choosing scopes

How scopes work

Naming

Available scopes

Choosing scopes