GitHat Server API Reference
Real endpoints grouped by area, sourced from all *router.js files under MicroBackEnds/src/handlers
Auth conventions
Three auth mechanisms appear across the API. 'Bearer / cookie' means the handler calls requireAuth(), which accepts the access JWT from either the Authorization: Bearer <token> header or the __Host-githat_access session cookie (legacy fallback: githat_access). 'X-GitHat-App-Key' means the handler calls resolveAppContext() with the app's publishable key in that header — no user JWT required. 'Bearer (SCIM token)' means the SCIM endpoint calls its own authenticate() helper that reads a bcrypt-stored per-org token from the Authorization: Bearer header (not a JWT). Webhook endpoints verified by Stripe or GitHub use their respective signature headers and carry no GitHat auth.
requireOrgAdmin and requireOrgMember layer on top of requireAuth — they also accept Bearer or cookie, and additionally check org membership and, where noted, role.
Authentication — /auth and /oauth
Source: src/handlers/auth/router.js. All routes are rate-limited by withRateLimit and abuse-scored by withAbuseGuard before the handler runs.
POST /auth/register Register a new user account public
POST /auth/login Password login, sets access + refresh cookies public
POST /auth/logout Invalidate current session Bearer / cookie
POST /auth/refresh Rotate refresh token, issue new access token cookie (refresh)
GET /auth/me Return the authenticated user record Bearer / cookie
GET /auth/verify Verify an email-link token (link click) public
POST /auth/verify-email Verify email with code from email public
POST /auth/resend-verification Resend email verification message public
POST /auth/forgot-password Send password-reset email public
POST /auth/reset-password Complete password reset with token public
POST /auth/change-password Change password (requires current password) Bearer / cookie
POST /auth/accept-invite Accept an org invite and complete registration public
DELETE /auth/me Delete the authenticated user's account Bearer / cookie
GET /auth/export GDPR export of the authenticated user's data Bearer / cookie
POST /oauth/revoke RFC 7009 — revoke a refresh token X-GitHat-App-Key
POST /oauth/introspect RFC 7662 — inspect any GitHat token X-GitHat-App-Key
GET /oauth/authorize RFC 6749 — begin "Continue with GitHat" cross-app flow Bearer / cookie (optional)
POST /oauth/token RFC 6749 — exchange authorization code for JWTs X-GitHat-App-Key
GET /auth/sessions List the authenticated user's active sessions Bearer / cookie
DELETE /auth/sessions/{id} Revoke a specific session Bearer / cookie
DELETE /auth/sessions Revoke all sessions for the current user Bearer / cookie
GET /auth/audit-log Fetch the current user's audit events Bearer / cookie
POST /auth/2fa/setup Generate TOTP secret for 2FA setup Bearer / cookie
POST /auth/2fa/enable Confirm TOTP code and activate 2FA Bearer / cookie
POST /auth/2fa/disable Disable TOTP 2FA Bearer / cookie
POST /auth/2fa/login-verify Verify TOTP code during login public
POST /auth/2fa/recovery-codes/regenerate Regenerate TOTP backup codes Bearer / cookie
POST /auth/mfa/sms/enroll Enroll a phone number for SMS OTP Bearer / cookie
POST /auth/mfa/sms/verify Verify SMS OTP to complete enrollment Bearer / cookie
POST /auth/mfa/sms/challenge Send a new SMS OTP challenge during login public
POST /auth/mfa/sms/disable Disable SMS MFA Bearer / cookie
POST /auth/magic-link/request Send a magic-link email public
POST /auth/magic-link/verify Verify magic-link token and issue session public
POST /auth/passkey/register-options Get WebAuthn credential-creation options Bearer / cookie
POST /auth/passkey/register-verify Verify and store new passkey Bearer / cookie
POST /auth/passkey/login-options Get WebAuthn assertion options public
POST /auth/passkey/login-verify Verify passkey assertion and issue session public
DELETE /auth/passkey/{credentialId} Remove a registered passkey Bearer / cookie
POST /auth/device/code Initiate OAuth 2.0 device authorization (CLI) public
POST /auth/device/token Poll for device token after user approval public
POST /auth/device/verify Approve a pending device code (user-facing) Bearer / cookie
GET /auth/oauth/github/url Get GitHub OAuth redirect URL public
POST /auth/oauth/github Exchange GitHub code for GitHat session public
GET /auth/oauth/cognito/url Get Cognito OAuth redirect URL public
POST /auth/oauth/cognito Exchange Cognito code for GitHat session public
GET /auth/oauth/google/url Get Google OAuth redirect URL public
POST /auth/oauth/google Exchange Google code for GitHat session public
POST /auth/oauth/google/onetap Verify a Google One Tap ID token public
GET /auth/oauth/microsoft/url Get Microsoft OAuth redirect URL public
POST /auth/oauth/microsoft Exchange Microsoft code for GitHat session public
GET /auth/oauth/facebook/url Get Facebook OAuth redirect URL public
POST /auth/oauth/facebook Exchange Facebook code for GitHat session public
GET /auth/oauth/apple/url Get Apple OAuth redirect URL public
POST /auth/oauth/apple Exchange Apple code for GitHat session public
GET /auth/oauth/instagram/url Get Instagram OAuth redirect URL public
POST /auth/oauth/instagram Exchange Instagram code for GitHat session public
GET /auth/oauth/tiktok/url Get TikTok OAuth redirect URL public
POST /auth/oauth/tiktok Exchange TikTok code for GitHat session public
POST /auth/captcha/verify Verify a Cloudflare Turnstile token public
GET /admin/abuse-reports List abuse reports (platform-owner only) Bearer / cookie (platform-owner)Organizations — /org and /orgs
Source: src/handlers/org/router.js. All routes require at minimum org membership (Bearer / cookie). Admin-or-owner role required for create, update, delete, invite, logo upload, and metadata updates.
POST /org Create a new organization Bearer / cookie
GET /org/{id} Get organization details and members Bearer / cookie (member)
PATCH /org/{id} Update org name, slug, branding Bearer / cookie (admin)
DELETE /org/{id} Delete the organization Bearer / cookie (owner)
GET /org/{id}/export GDPR export of org data Bearer / cookie (admin)
GET /org/{id}/members List org members Bearer / cookie (member)
POST /org/{id}/members Invite a new member by email Bearer / cookie (admin)
PATCH /org/{id}/members/{userId} Update a member's role Bearer / cookie (admin)
DELETE /org/{id}/members/{userId} Remove a member from the org Bearer / cookie (admin)
POST /org/{id}/logo/upload-url Get S3 presigned URL for logo upload Bearer / cookie (admin)
POST /org/{id}/invites/{email}/resend Resend an existing invite email Bearer / cookie (admin)
DELETE /org/{id}/invites/{email} Cancel a pending invite Bearer / cookie (admin)
GET /orgs/{id}/metadata Get org custom metadata Bearer / cookie (member)
PATCH /orgs/{id}/metadata Update org custom metadata Bearer / cookie (admin)Apps — /apps
Source: src/handlers/apps/router.js. All routes require Bearer / cookie auth at minimum. Dashboard-facing sub-resources (webhooks, storage, deploy) pass through the same session cookie path rather than X-GitHat-App-Key, because the dashboard proxy strips x-githat-* headers.
GET /apps List apps owned by the authenticated user Bearer / cookie
POST /apps Create a new app Bearer / cookie
GET /apps/{appId} Get app details Bearer / cookie
PATCH /apps/{appId} Update app settings Bearer / cookie
DELETE /apps/{appId} Delete an app Bearer / cookie
POST /apps/{appId}/cloudfront Provision a CloudFront distribution for the app Bearer / cookie
POST /apps/{appId}/domains Add a custom domain at the CDN level Bearer / cookie
POST /apps/{appId}/domains/attach Attach a custom domain to the CDN distribution Bearer / cookie
POST /apps/{appId}/domain Add an app-level DNS domain Bearer / cookie
POST /apps/{appId}/domain/verify Verify DNS propagation for the app domain Bearer / cookie
GET /apps/{appId}/domain Get the current app domain record Bearer / cookie
DELETE /apps/{appId}/domain Remove the app domain Bearer / cookie
POST /apps/{appId}/keys Create an API key (publishable or secret) Bearer / cookie
GET /apps/{appId}/keys List API keys for the app Bearer / cookie
DELETE /apps/{appId}/keys/{keyId} Delete an API key Bearer / cookie
GET /apps/{appId}/users List end-users who have authenticated through this app Bearer / cookie
GET /apps/{appId}/webhooks List webhooks for this app (dashboard) Bearer / cookie
POST /apps/{appId}/webhooks Create a webhook for this app (dashboard) Bearer / cookie
DELETE /apps/{appId}/webhooks/{webhookId} Delete a webhook for this app (dashboard) Bearer / cookie
GET /apps/{appId}/storage List storage objects for this app (dashboard) Bearer / cookie
DELETE /apps/{appId}/storage/{objectId} Delete a storage object (dashboard) Bearer / cookie
POST /apps/{appId}/deploy Deploy a gzipped tar of the app's out/ dir via CLI Bearer / cookie (or sk_live_ key)User — /user
Source: src/handlers/user/router.js. All routes require Bearer / cookie auth.
GET /user/orgs List orgs the current user belongs to Bearer / cookie
POST /user/orgs/{id}/switch Switch the active org context in the session Bearer / cookie
PATCH /user/profile Update display name, bio, etc. Bearer / cookie
POST /user/avatar/upload-url Get S3 presigned URL for avatar upload Bearer / cookie
POST /user/avatar/restore-from-oauth Restore avatar from the linked OAuth provider Bearer / cookieWebhooks — /webhooks
Source: src/handlers/user/router.js (the /webhooks/* routes are mounted there). These are org-admin-scoped via X-GitHat-App-Key combined with requireOrgAdmin. The webhook creation handler explicitly documents that it requires X-GitHat-App-Key plus an org-admin Bearer / cookie token.
POST /webhooks Register a webhook endpoint Bearer / cookie (org admin) + X-GitHat-App-Key
GET /webhooks List registered webhooks Bearer / cookie (org admin) + X-GitHat-App-Key
GET /webhooks/{id} Get a specific webhook Bearer / cookie (org admin) + X-GitHat-App-Key
PATCH /webhooks/{id} Update a webhook (URL, events, secret) Bearer / cookie (org admin) + X-GitHat-App-Key
DELETE /webhooks/{id} Delete a webhook Bearer / cookie (org admin) + X-GitHat-App-Key
GET /webhooks/{id}/deliveries List recent delivery attempts for a webhook Bearer / cookie (org admin) + X-GitHat-App-KeyBilling — /billing and /usage
Source: src/handlers/billing/router.js. Stripe billing webhooks are verified by Stripe-Signature, not user auth. Usage tracking requires X-GitHat-App-Key; usage querying requires org-admin role. The /billing/admin/cost route is platform-admin restricted.
POST /billing/checkout-session Create a Stripe Checkout session (legacy) Bearer / cookie (org admin)
POST /billing/portal-session Open Stripe Customer Portal (legacy) Bearer / cookie (org admin)
POST /billing/webhook Stripe webhook receiver for GitHat billing Stripe-Signature (no user auth)
GET /billing/org Get the org's current billing plan Bearer / cookie (org admin)
POST /billing/org/checkout Start a Stripe Checkout for an org plan upgrade Bearer / cookie (org admin)
POST /billing/org/portal Open Stripe Customer Portal for org billing Bearer / cookie (org admin)
POST /billing/org/cancel Cancel the org's active subscription Bearer / cookie (org admin)
POST /billing/app/connect Connect an app to billing Bearer / cookie
GET /billing/app Get the app's billing record Bearer / cookie
POST /billing/app/checkout Start a Stripe Checkout for an app plan Bearer / cookie
POST /billing/app/portal Open Stripe Customer Portal for app billing Bearer / cookie
POST /usage/track Record a metered usage event for an app X-GitHat-App-Key
GET /usage Query usage totals for an app Bearer / cookie (org admin)
GET /usage/meters List available usage meter definitions Bearer / cookie (org admin)
GET /billing/admin/cost Per-customer cost and margin report (platform-admin) Bearer / cookie (platform admin)Storage — /storage
Source: src/handlers/storage/router.js. Every endpoint requires both a valid user Bearer / cookie token AND the X-GitHat-App-Key header to scope the operation to an app.
POST /storage/presign-upload Get an S3 presigned PUT URL for a new object Bearer / cookie + X-GitHat-App-Key
POST /storage/finalize/{objectId} Mark an uploaded object as complete Bearer / cookie + X-GitHat-App-Key
GET /storage/objects List app storage objects for the current user Bearer / cookie + X-GitHat-App-Key
GET /storage/objects/{id} Get metadata for a storage object Bearer / cookie + X-GitHat-App-Key
DELETE /storage/objects/{id} Delete a storage object Bearer / cookie + X-GitHat-App-Key
PATCH /storage/objects/{id} Update storage object metadata Bearer / cookie + X-GitHat-App-KeyAgents, MCP, and Eliza — /agent, /mcp, /eliza, /verify
Source: src/handlers/agent/router.js (all six areas are mounted in this one Lambda). Agent and Eliza registration and management require user Bearer / cookie. The challenge-then-token flow for agents and the verify-then-token flow for MCP issue short-lived Bearer tokens (type:'agent' / type:'mcp' / type:'eliza') which have their own requireAgentAuth / requireMCPAuth / requireElizaAuth middleware used by downstream resource endpoints. The public /verify/* endpoints are unauthenticated.
POST /agent/register Register a new AI agent (Ethereum wallet-based) Bearer / cookie
POST /agent/challenge Get a sign challenge for the agent wallet public
POST /agent/token Exchange signed challenge for an agent Bearer token public (signed challenge)
POST /agent/{id}/suspend Suspend an agent (owner or admin) Bearer / cookie
POST /agent/{id}/reactivate Reactivate a suspended agent Bearer / cookie
GET /agent/list List agents owned by the authenticated user Bearer / cookie
GET /agent/{id}/logs Fetch activity logs for an agent Bearer / cookie
POST /eliza/register Register a new ElizaOS / Web4 agent Bearer / cookie
POST /eliza/token Exchange Eliza credentials for a Bearer token Bearer / cookie
POST /eliza/{elizaId}/suspend Suspend an Eliza agent (kill switch or owner JWT) Bearer / cookie or kill-switch token
POST /eliza/{elizaId}/reactivate Reactivate a suspended Eliza agent Bearer / cookie
GET /eliza List Eliza agents owned by the current user Bearer / cookie
POST /mcp/register Register a new MCP server Bearer / cookie
POST /mcp/verify Verify domain ownership for an MCP server Bearer / cookie
POST /mcp/token Exchange MCP server credentials for a Bearer token Bearer / cookie
PATCH /mcp/{id} Update MCP server metadata Bearer / cookie
POST /mcp/{id}/revoke Revoke an MCP server's token Bearer / cookie
GET /mcp/list List MCP servers owned by the current user Bearer / cookie
GET /mcp/{id}/logs Fetch activity logs for an MCP server Bearer / cookie
GET /verify/mcp/{domain} Public lookup: is this domain a registered MCP server? public
GET /verify/agent/{wallet} Public lookup: is this wallet a registered agent? publicSCIM 2.0 — /scim/v2
Source: src/handlers/scim/router.js. Discovery endpoints (ServiceProviderConfig, Schemas, ResourceTypes) are unauthenticated. All user and group endpoints require Authorization: Bearer <scim-token> where the token is a per-org SCIM bearer token stored (bcrypt-hashed) in DynamoDB — not a user JWT.
GET /scim/v2/ServiceProviderConfig SCIM server capabilities public
GET /scim/v2/Schemas SCIM schema definitions public
GET /scim/v2/ResourceTypes SCIM resource type definitions public
GET /scim/v2/Users List users (with filter support) Bearer (SCIM token)
POST /scim/v2/Users Provision a new user Bearer (SCIM token)
GET /scim/v2/Users/{id} Get a user Bearer (SCIM token)
PATCH /scim/v2/Users/{id} Partially update a user (SCIM PATCH ops) Bearer (SCIM token)
PUT /scim/v2/Users/{id} Full replace of a user record Bearer (SCIM token)
DELETE /scim/v2/Users/{id} Deprovision a user (sets active:false) Bearer (SCIM token)
GET /scim/v2/Groups List groups Bearer (SCIM token)
GET /scim/v2/Groups/{id} Get a group Bearer (SCIM token)Analytics, Observability, and Deployments — /analytics, /observability, /deployments
Source: src/handlers/analytics/router.js. All endpoints require Bearer / cookie. Analytics endpoints additionally enforce org-admin or owner role when deriving the orgId from the appId.
GET /analytics/app/{appId}/overview Auth event counts, MAU, DAU for an app Bearer / cookie
GET /analytics/app/{appId}/timeseries Time-series auth events for an app Bearer / cookie
GET /analytics/app/{appId}/top-users Top users by event volume for an app Bearer / cookie
GET /analytics/app/{appId}/funnels Auth funnel conversion metrics for an app Bearer / cookie
GET /analytics/org/{orgId}/overview Aggregate analytics across all org apps Bearer / cookie
GET /observability/lambdas Lambda health metrics (platform-admin) Bearer / cookie
GET /observability/api-gateway API Gateway metrics (platform-admin) Bearer / cookie
GET /deployments List recent deployments Bearer / cookie
GET /deployments/{id} Get deployment details Bearer / cookie
GET /deployments/{id}/logs Get deployment logs Bearer / cookie
POST /deployments/{id}/redeploy Trigger a re-deployment Bearer / cookie
GET /deployments/health Aggregated deployment health summary Bearer / cookie
GET /deployments/recent-failures List recent failed deployments Bearer / cookie
GET /deployments/per-app List deployments grouped by app Bearer / cookieDomains — /domains
Source: src/handlers/domains/router.js. All routes require Bearer / cookie. The availability check is the only one that may be treated as quasi-public (no org-specific data returned), but it still runs through requireAuth.
POST /domains/onboard Begin custom-domain onboarding for an app Bearer / cookie
GET /domains/onboard/{appId}/{domain} Get onboarding status for a domain Bearer / cookie
POST /domains/onboard/{appId}/{domain}/check Recheck DNS and SSL for a domain in progress Bearer / cookie
DELETE /domains/onboard/{appId}/{domain} Cancel and remove a domain onboarding record Bearer / cookie
GET /domains/availability Check if a domain name is registrable Bearer / cookie
POST /domains/register Register a domain name via Route 53 Bearer / cookie
GET /domains/register/{operationId} Poll the status of a domain registration operation Bearer / cookieEmail — /email and /apps/{appId}/email
Source: src/handlers/email/router.js. The top-level /email/send is scoped to the platform; the /apps/{appId}/email/* routes scope to a specific app. All require Bearer / cookie.
POST /email/send Send a transactional email (platform-level sender) Bearer / cookie
POST /apps/{appId}/email/send Send a transactional email via the app's sender Bearer / cookie
POST /apps/{appId}/email/domains Add a sending domain for an app Bearer / cookie
GET /apps/{appId}/email/domains List sending domains for an app Bearer / cookie
GET /apps/{appId}/email/domains/{hostname} Get verification status for a sending domain Bearer / cookie
DELETE /apps/{appId}/email/domains/{hostname} Remove a sending domain Bearer / cookieGitHub integration — /github
Source: src/handlers/github/router.js. The webhook receiver authenticates via X-Hub-Signature-256 (GitHub's HMAC-SHA256 delivery signature), not a user token.
POST /github/authorize Start a GitHub App installation OAuth flow Bearer / cookie
GET /github/callback Handle GitHub OAuth callback and store installation Bearer / cookie
POST /github/webhook Receive GitHub webhook events X-Hub-Signature-256 (no user auth)
GET /github/installations List GitHub App installations for the current user Bearer / cookie
DELETE /github/installations/{id} Disconnect a GitHub App installation Bearer / cookie
GET /github/installations/{id} Get a specific GitHub App installation Bearer / cookie
PATCH /github/installations/{id} Update installation settings Bearer / cookieSkills marketplace — /skills and /ratings
Source: src/handlers/skills/router.js. GET /skills (list) is public. GET /skills/{slug} is also nominally public but calls requireAuth to surface auth-specific fields (starred, installed state). All write operations and the installed list require Bearer / cookie.
GET /skills List marketplace skills (public) public
POST /skills Publish a new skill to the marketplace Bearer / cookie
GET /skills/installed List skills installed by the current user Bearer / cookie
GET /skills/{slug} Get skill details (auth enriches the response) Bearer / cookie
GET /skills/{slug}/versions List published versions of a skill Bearer / cookie
GET /skills/{slug}/download Download the skill package Bearer / cookie
POST /skills/{slug}/versions Publish a new version of a skill Bearer / cookie
POST /skills/{slug}/star Star a skill Bearer / cookie
DELETE /skills/{slug}/star Unstar a skill Bearer / cookie
POST /skills/{slug}/report Report a skill for review Bearer / cookie
POST /skills/{slug}/install Install a skill to the current user's account Bearer / cookie
DELETE /skills/{slug}/install Uninstall a skill Bearer / cookie
POST /ratings/submit Submit a rating for a skill Bearer / cookie
GET /ratings/aggregate Get aggregate ratings for a skill publicSebastn (Stripe Connect) — /sebastn
Source: src/handlers/billing/router.js (Sebastn routes are mounted there). The onboard-webhook receiver uses STRIPE_SEBASTN_WEBHOOK_SECRET (a separate Stripe webhook secret from the GitHat billing webhook) for Stripe-Signature verification — no user auth.
ANY /sebastn/checkout/sessions Create or interact with a Stripe Checkout session Bearer / cookie
ANY /sebastn/onboard/accounts Create or manage a Stripe Connect merchant account Bearer / cookie
ANY /sebastn/onboard/done Handle Stripe Connect onboarding return Bearer / cookie
ANY /sebastn/merchants/{accountId} Get Stripe Connect merchant details Bearer / cookie
POST /sebastn/webhook/stripe Stripe Connect webhook receiver Stripe-Signature (no user auth)Status, well-known, and legal — /status, /.well-known, /legal
Source: src/handlers/status/router.js (which also imports src/handlers/legal/router.js). All routes here are public except POST /admin/status/incidents, which is restricted to the platform-owner allowlist.
GET /health Lambda health probe public
GET /status Public platform status page summary public
GET /status/canary Canary check for synthetic monitoring public
GET /status/uptime Uptime history for all platform components public
GET /status/incidents List active and recent incidents public
POST /admin/status/incidents Create or update a status incident Bearer / cookie (platform-owner)
GET /.well-known/openid-configuration OpenID Connect discovery document public
GET /.well-known/jwks.json JWKS public-key set for token verification public
GET /.well-known/security.txt Security contact info (RFC 9116) public
GET /.well-known/webfinger WebFinger resource lookup public
GET /openapi.json OpenAPI spec (JSON) public
GET /openapi.yaml OpenAPI spec (YAML) public
GET /robots.txt Search engine crawl directives public
GET /metrics Prometheus-format metrics public
GET /legal Index of all legal documents with metadata public
GET /legal/terms Terms of Service (jurisdiction-localised) public
GET /legal/privacy Privacy Policy (jurisdiction-localised) public
GET /legal/cookie-policy Cookie Policy (en/eu/uk only) public
GET /legal/dpa Data Processing Addendum (en only) public