GraphQL

Permissions

The API enforces the same role permissions as the product. API OAuth tokens inherit the authorizing user. MCP has additional mcp.read and mcp.write checks.

Constructable authorization is role-based. The API does not have a separate permission model. Whatever the user can do in the product, the same token can do through GraphQL. Whatever they cannot do is rejected.

How it is enforced

Queries load records through permission scopes. Lists omit records the user cannot see. Singular lookups (rfi(id:)) return null when the record is out of scope.
Mutations declare a policy action such as rfis.write or projects.read. If the role lacks that action, the mutation returns a GraphQL error.
Nested project mutations also require projects.read on the target project before the inner mutation runs.
Soft-deleted records are excluded from normal queries.

Company users (subcontractors, owners, architects) see a narrower slice than organization employees. A company membership session is scoped to that company and the projects it is on. An organization API OAuth token for a company user is the same: it can only see what that company membership can see in the client organization.

Organization API OAuth

API access tokens inherit the authorizing user's role in the organization that owns the client. They cannot escalate, switch organizations, or manage API clients.

Action	Who
Create or revoke an API client	Organization admin (`organization_settings.write`). Session only.
Authorize an existing client	Any user who belongs to that organization, including company users.
Call GraphQL with the token	That user's product permissions, re-checked on every request.

API tokens do not expose user mutations or createOauthApplication / revokeOauthApplication. Revoke the client in Organization Settings if the integration should lose access immediately.

MCP

MCP adds two role actions on top of product permissions:

Action	Effect
`mcp.read`	Required to use MCP at all. Without it, an existing OAuth token cannot run tools.
`mcp.write`	Required for write tools (`mutate_graphql`, `constructable.mutateGraphql`). Without it, the server exposes only read tools.

Administrators, managers, and employees receive MCP access by default. Custom roles can have these actions removed. See MCP.

MCP still cannot exceed the user's project and record permissions. Connecting an assistant does not grant extra organization access.

Super-user fields

A few organization fields exist only for Constructable super users (for example billing metadata). They appear in the schema dump and resolve to hidden or inaccessible values for everyone else. Do not depend on them in customer integrations.

Practical checks

Sign in as the user you will automate.
Confirm they can perform the action in the product UI.
Call the matching mutation.
If it fails with a permission error, change the role under organization settings rather than trying a different API field.

Role configuration is documented for product users in Roles and permissions.