Skip to main content

Authentication and permissions

GraphQL uses the same authentication model as REST. Send an OAuth2/OIDC access token as a Bearer token on both endpoints:

curl -X POST "https://api.tourfold.com/api/v2/graphql" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"{ equipment(first: 1) { edges { node { id created_at } } } }"}'

Replace equipment with a definition slug from your own workspace, and note the shape: a connection must be selected through edges { node { โ€ฆ } }, and page size is first โ€” there is no limit argument.

Use the Authorization Code flow for user-facing applications and Client Credentials for server-to-server integrations. Flows, endpoints and token lifetimes are documented once, for both surfaces, under REST authentication.

Read grantsโ€‹

Both endpoints require authentication. Downloading the schema does not require a record grant. Each root, relationship, reference filter and relationship sort enforces its resource owner's read policy before selecting data or counting records:

ResourceRead policy
Custom Objectsobjects:records:read, plus the definition's access policy
Vehiclesvehicles:read
Taskstasks:read
Tours (system_tour)tours:read, or tours:read:own (scoped to published Tours where the caller is a participant); tasks:read when expanding task_visit Stops, tasks, or task_assignments
Skillsskills:read
Usersusers:read
Devicesdevices:read
TagsAuthenticated access, matching the native Tag API
BW Cases and Activitiescases:read, with the BW plugin enabled
BW Jobscases:read or tours:read, with the BW plugin enabled
BW Tourstours:read, with the BW plugin enabled

A Skills-only reader can query Skills without Object grants. An Object-only reader cannot query Skills, including through a relationship or a filter that would otherwise return zero rows. Write permissions remain separate and apply to the corresponding native REST APIs.

Per-type accessโ€‹

In addition to the Object read grant, individual object types can be access-restricted. Object metadata is tenant-visible and stable: all tenant types remain in the generated schema. Record data is checked per type, during execution, and denied fields produce explicit GraphQL errors:

SituationResult
A restricted type you may not read, at the rootdata is null because root connections are non-null; errors[] identifies the field
A restricted type reached through a to-one relationThe relation field is null and errors[] identifies that field
A restricted type reached through a to-many relationThe relation field is null and errors[] identifies that field
A type that exists only as a child of another recordNever available at the root; only through its parent

When GraphQL nullability permits it, readable sibling fields remain in data. A denied error has stable extensions.code = "https://problems.tourfold.com/access-denied" and extensions.data = {"reason":"not_member","type":"object:<slug>"}. Clients can therefore distinguish an empty collection from an authorization failure without parsing message text.

Native definitions have no editable per-object permission matrix. Their owning feature supplies the read policy shown above. Selecting full Skill records through a Vehicle attribute requires skills:read; the Vehicle REST response can still include its authorized compact reference labels. Explicitly parent-scoped Object types remain accessible only through an authorized parent.

Authentication failures are HTTP errors, not GraphQL errorsโ€‹

Authentication and endpoint admission are enforced before the GraphQL engine runs, so failures surface as HTTP status codes with an RFC 9457 problem document โ€” not as entries in a GraphQL errors array:

StatusMeaning
401No token, an expired token, or an invalid token.

After admission, denied record access is a GraphQL field error on an HTTP 200 response. Missing owner grants use extensions.data.reason = "missing_grant" and list required_grants; a denied Object ACL uses reason = "not_member". Both use extensions.code = "https://problems.tourfold.com/access-denied". See Errors and limits.

Practical notesโ€‹

  • Tokens are workspace-scoped. Use a token issued for the workspace whose data you are querying.
  • Prefer short-lived access tokens with refresh tokens in user-facing applications; never embed a long-lived token in a client application.
  • The GraphQL API is read-only, so a token used only for querying needs only the relevant resource read permissions; these do not permit REST writes.