Scopes

Scopes control which operations an access token is permitted to perform. Every Houzz Pro API endpoint declares the scope (or one of a set of scopes) it requires; a request succeeds only when the token carries a matching scope.

The scope model

Scopes follow an action:resource naming convention. The prefix describes the level of access:

Prefix	Meaning
read:	Read and list a resource (e.g. read:projects).
write:	Create and update a resource (e.g. write:projects).
admin: / delete:	Elevated access, including deletion, deactivation, or archiving (e.g. admin:projects, delete:documents).

Most resources use admin: for their destructive tier. A few, such as documents, use delete: instead. The scope required by any given endpoint is listed in the API Reference.

How scopes are enforced

• Each endpoint requires a specific scope. If your token does not carry a scope that satisfies the endpoint, the request is rejected with 403 Forbidden.
• A token can only carry scopes that have been granted to your service account by Houzz. Requesting a scope you were not granted does not add it — contact your Houzz representative to change your grant.
• You select which of your granted scopes to put on a token via the scope parameter of the token request.

Request least privilege

Request only the scopes a given token needs. If a worker only reads projects, mint it a token with read:projects — not your full grant. Following the principle of least privilege limits the blast radius if a token ever leaks, and keeps your integration's access auditable.

# A read-only reporting job needs only read scopes.
curl --request POST \
  --url https://auth.houzz.com/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data audience=https://pro-api.houzz.com \
  --data 'scope=read:projects read:leads read:contacts'

Scope catalog

The full set of scopes, grouped by resource. This is the authoritative list; the API Reference shows the exact scope each operation requires.

API metadata

Scope	Description
read:api-metadata	View API version and available scopes.

Projects

Scope	Description
read:projects	View project details and list projects.
write:projects	Create and update projects.
admin:projects	Full administrative access to projects, including deletion.

Leads

Scope	Description
read:leads	View lead details and list leads.
write:leads	Create and update leads.
admin:leads	Full administrative access to leads, including deletion.

Schedule

Scope	Description
read:schedule	View milestones and schedule details.
write:schedule	Create and update milestones.
admin:schedule	Full administrative access to schedule, including deletion.

Daily logs

Scope	Description
read:daily-logs	View daily log details and list daily logs.
write:daily-logs	Create and update daily logs.
admin:daily-logs	Full administrative access to daily logs, including deletion.

Tasks

Scope	Description
read:tasks	View tasks, punchlist, and related items.
write:tasks	Create and update tasks and punchlist visibility.
admin:tasks	Full administrative access to tasks, including deletion.

Documents

Scope	Description
read:documents	View documents and their contents.
write:documents	Create and update documents.
delete:documents	Permanently delete documents.

Files

Scope	Description
read:files	View file details and list files.
write:files	Upload and update files.
admin:files	Delete files.

Team members

Scope	Description
read:team-members	View team member details and list them.
write:team-members	Invite and update team members.
admin:team-members	Deactivate and archive team members.

Subcontractors

Scope	Description
read:subcontractors	View subcontractor details and list them.
write:subcontractors	Invite and update subcontractors.
admin:subcontractors	Deactivate and archive subcontractors.

Vendors

Scope	Description
read:vendors	View vendor details and list vendors.
write:vendors	Create and update vendors.
admin:vendors	Archive vendors.

Entity assignments

Scope	Description
read:entity-assignments	View entity assignments and candidates.
write:entity-assignments	Assign and reassign entities.

Contacts

Scope	Description
read:contacts	View contact details and list contacts.
write:contacts	Create and update contacts.
admin:contacts	Delete contacts.

note

Webhook subscription and webhook trigger endpoints are authenticated but are not gated by a named scope. Any valid token for your service account can manage webhook subscriptions. See Webhooks.