The GitHub Org Tools API is a security layer between your client and the GitHub API. It handles authentication, session persistence, installation lifecycle, and request filtering — so your frontend doesn’t have to.

Endpoint categories

Request flow

Client (Web/Mobile)
       │
       ▼
[ API Route Handlers ] ───► [ Session Store (Supabase) ]
       │                           │
       ▼                           ▼
[ Auth/Allowlist Logic ]    [ Normalized DB ]
       │                    (users, orgs, memberships)
       ▼
[ GitHub API (GraphQL/REST) ]

Security model at a glance

Session validation

Every protected route checks the session via:

1. Authorization: Bearer <sessionId> header (mobile apps or API clients)
2. gh_session httpOnly cookie (web browsers)

The session ID is looked up in Supabase auth_sessions, joined with users and organization_memberships + organizations. The GitHub OAuth token is decrypted server-side with AES-256-GCM.

Operation allowlisting

The GraphQL proxy only allows a specific set of 8 named operations. You can’t send arbitrary GraphQL — the operationName must match the allowlist:

• ViewerProfile
• OrganizationSummary
• SearchUsers
• OrgRepositories
• RepoScoringData
• OrgTeamsData
• OrgScoringData
• OrganizationRepositories

See GraphQL API for details.

CSRF protection

OAuth and installation flows use signed HS256 state JWTs and temporary CSRF cookies (gh_auth_csrf, gh_install_csrf). Details in Security Model.

Webhook verification

GitHub App webhook payloads are verified with HMAC-SHA256 using GITHUB_WEBHOOK_SECRET. See Webhook API.

Request lifecycle

1. Request comes into an API route
2. Auth — route validates session via getRequestSession()
3. Logic — for REST routes, executes business logic (e.g., mass invite). For GraphQL, verifies operationName is allowlisted
4. GitHub call — server uses the decrypted session token to call GitHub
5. Response — result is sanitized and returned to client

Error codes

Related docs