Let users connect their GitHub account to the Vouched KYA gateway for OAuth-backed tool calls

Overview

GitHub is the first upstream provider supported by the Vouched KYA gateway's connections flow. End users can click Connect GitHub on any gateway upstream card that points at a GitHub MCP server. Their next tool call through the gateway automatically injects their personal access token as GITHUB_TOKEN: no pasted PATs, no scope guessing, no credential rotation reminders.

User clicks Connect GitHub
  → github.com consent screen
  → redirect back with auth code
  → gateway exchanges code for access token
  → token encrypted at rest
  → next tool call has GITHUB_TOKEN available

"Connections" (outbound) and "delegations" (inbound) are distinct concepts. A delegation is the VC-JWT Vouched KYA issues to an MCP client proving "Alice from Acme is calling"; see KYA-OS delegations. A connection is the OAuth access token Vouched KYA holds on behalf of Alice so the gateway can call an upstream provider like GitHub as her. Both involve OAuth; neither is "the" OAuth.

What the end user sees

Dashboard → the Gateway section of your org → a GitHub-backed upstream card with "Credentials not configured"
Click the card → the hybrid credential modal opens with a green primary Connect GitHub button
Click Connect GitHub → browser navigates to github.com/login/oauth/authorize?…
If already signed into GitHub (or into an SSO IdP GitHub trusts), the consent screen appears immediately showing the requested scopes
Click Authorize Vouched KYA Gateway → GitHub redirects back to https://kya.vouched.id/api/v1/gateway/connections/github/callback?code=…&state=…
The gateway validates the state token, exchanges the code for an access token, and stores the encrypted token against Alice's account
The modal updates to "Connected as alice@vouched.id via GitHub"
Alice's next gateway tool call that targets the GitHub MCP upstream automatically has GITHUB_TOKEN injected into the request environment

Scopes requested

The GitHub OAuth App requests exactly two scopes:

repo: read/write access to public and private repos the user owns or collaborates on. This is the minimum scope the MCP GitHub server needs to actually do anything useful. Lesser scopes like public_repo leave private-repo tool calls broken.
user:email: read the authenticated user's email, used solely to display "Connected as alice@example.com" in the credential modal. Never used for an authentication decision.

We deliberately do not request admin:org, delete_repo, workflow, or anything broader. Scope sprawl would make users hesitant to authorize Vouched KYA. If a future MCP tool genuinely needs a broader scope, that requires a reviewed engineering change with an explicit changelog entry, never a drive-by addition, since it would widen the access every connected user has already granted.

Token lifecycle

GitHub OAuth App access tokens never expire under default configuration. A token is only invalidated if:

The user explicitly revokes Vouched KYA via github.com/settings/applications
GitHub detects suspicious activity on the user's account and revokes all OAuth grants
Vouched KYA revokes its GitHub OAuth App from the GitHub developer console, which revokes every connected user's token at once
The user clicks Disconnect in Vouched KYA's credential modal: the gateway permanently deletes the stored token (no GitHub-side revoke because OAuth Apps don't expose a REST revoke endpoint; users revoke via GitHub's settings UI)

Because tokens don't expire, the gateway's lazy-refresh path skips the expiry-near-now check entirely for GitHub connections: the tokenExpiryStrategy: 'never_expires' in the provider registry signals this to the vault resolve endpoint.

Troubleshooting

Cause: The callback URL the gateway sends doesn't match the one registered on Vouched KYA's GitHub OAuth App. That is a configuration problem on Vouched KYA's side, not in your GitHub account. So is a 503 when you click Connect GitHub: it means the gateway's GitHub OAuth credentials aren't configured.

Fix: Report it to kya+support@vouched.id.

"Bad credentials" on tool calls after a successful Connect GitHub

Cause: The token was revoked externally: either by the user at github.com/settings/applications or by GitHub's automated fraud detection.

Fix: The user must click Disconnect in the Vouched KYA credential modal, then Connect GitHub again. The gateway's vault resolve endpoint can't auto-detect revocation (GitHub doesn't push revocation events to OAuth clients), so the first failing tool call after revocation surfaces a bad credentials error to the user and the reconnect is manual.

`state mismatch` error in the gateway logs on callback

Cause: The CSRF state token the browser returned from GitHub doesn't match a state the gateway issued. Either:

More than 10 minutes elapsed between authorize and callback (state TTL expired)
The user opened the authorize URL in one browser and completed the flow in another
Someone is attempting a CSRF attack

Fix: Have the user restart the connect flow. If it keeps happening inside the 10-minute window, report it to kya+support@vouched.id.

Reference

GitHub OAuth Apps docs: upstream authoritative source
Refreshing user access tokens: token expiration and revocation details
KYA-OS delegations: the complement, for the inbound half of the credential story

GitHub Connections