Authorization Patterns

Role-based access

Define a permission branch on each endpoint for each supported role. Missing roles are rejected.

{ type: "DELETE", admin: ALL, editor: NONE, viewer: NONE }

Field-level permissions

viewer: {
  allowed: ["id", "display_name", "avatar_url"],
  disallowed: ["email", "password_hash"]
}

Ownership-based row access

user: {
  allowed: {
    field: ["id", "title", "owner_id"],
    where: { field: "owner_id", operator: "=", value: "$user.id" }
  },
  disallowed: []
}

Multi-tenant isolation

Bind every protected table to the tenant identity established by the server-side session.

where: { field: "workspace_id", operator: "=", value: "$user.workspace_id" }

Apply the same principle to joined tables and mutation endpoints; a tenant filter on only one read path is not an isolation strategy.

Payload-dependent authorization

Use $data to evaluate the proposed mutation. For example, a transition can require a specific current state and an intended next state.

Administrative override

Prefer an explicit admin branch such as ALL over hidden exceptions. This keeps elevated access reviewable in the structure.

Anti-patterns

• Trusting a role string supplied by the client.
• Adding VoidQL checks to reads but bypassing them for background jobs or mutations.
• Using ALL for convenience without a documented reason.
• Relying on response filtering after unauthorized rows were fetched.
• Treating field denial as a substitute for tenant row isolation.

← Query Operations · Validation & Workflows →