Skip to main content

GraphQL Schema Reference

This document provides an overview of the GraphQL schema. For the complete, authoritative schema definitions, see the .graphql files in packages/shared-graphql/src/schemas/.

Schema Files​

FileDescription
schema.graphqlBase types: Role, ApiError, AuthInfo, Query, Mutation
user/schema.graphqlUser type and self-service operations
org/schema.graphqlOrganization, Membership types and operations

Directives​

@auth​

Authorization directive for controlling field-level access. Used for documentation and future OAuth enforcement.

  • @auth(requires: USER) - Requires authentication
  • @auth(requires: ADMIN) - Requires admin role

Enums​

Role​

User authorization roles: ADMIN, USER, GUEST

OrganizationRole​

Organization membership roles: OWNER, ADMIN, MEMBER

Core Types​

Response Pattern​

All mutations return response wrappers with data and error fields:

  • UserResponse - User operations
  • OrganizationMembershipResponse - Membership operations

ApiError​

Standard error type with code (string) and message (string) fields.

AuthInfo​

Current session information with isAuthenticated, user, and expiresAt fields.

Domain Types​

User Domain​

  • User - id, email, emailVerified, firstName, lastName, displayName, avatarUrl, bio, onboardedAt, timestamps. Identity fields mirror WorkOS and are read-only; displayName and bio are ours
  • User - Session user info with id, email, name, image

Organization Domain​

  • Organization - Organization with id, name, slug, description, timestamps, members
  • OrganizationMembership - Membership with id, userId, organizationId, role, timestamps

Input Types​

User Inputs​

  • UpdateUserInput - displayName, bio (both optional). Deliberately excludes everything WorkOS owns

Organization Inputs​

  • InviteOrganizationMemberInput - email (required), role (required)

Exploring the Schema​

The best way to explore the schema is through:

  1. Apollo Sandbox - Visit /api/graphql in development
  2. Source files - Browse packages/shared-graphql/src/schemas/*.graphql
  3. Generated types - See packages/shared-graphql/src/generated/types.ts after running nx generate shared-graphql