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:
| Resource | Read policy |
|---|---|
| Custom Objects | objects:records:read, plus the definition's access policy |
| Vehicles | vehicles:read |
| Tasks | tasks: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 |
| Skills | skills:read |
| Users | users:read |
| Devices | devices:read |
| Tags | Authenticated access, matching the native Tag API |
| BW Cases and Activities | cases:read, with the BW plugin enabled |
| BW Jobs | cases:read or tours:read, with the BW plugin enabled |
| BW Tours | tours: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:
| Situation | Result |
|---|---|
| A restricted type you may not read, at the root | data is null because root connections are non-null; errors[] identifies the field |
| A restricted type reached through a to-one relation | The relation field is null and errors[] identifies that field |
| A restricted type reached through a to-many relation | The relation field is null and errors[] identifies that field |
| A type that exists only as a child of another record | Never 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:
| Status | Meaning |
|---|---|
401 | No 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.