GitHub OAuth2 Exchange

Authenticate users via GitHub's OAuth2 to retrieve access tokens and user profile data.

The GitHub OAuth2 Exchange block is used to exchange an authorization code for a GitHub access token and user profile information. This is used for "Log in with GitHub" or accessing GitHub repositories and account data via API.

Core Concept

When a user authorizes your app on GitHub, they return to your site with a temporary code. This block sends that code back to GitHub along with your app's credentials to prove your identity and receive a long-term access token.

Configuration

Field	Required	Description
Client ID	✅	Your GitHub application's Client ID from the GitHub Developer Settings.
Client Secret	✅	Your GitHub application's Client Secret. Must be stored as a Secret.
Redirect URI	✅	The URI where GitHub redirects the user after authorization.
Authorization Code	✅	The code received from GitHub (e.g., `{request.query.code}`).
Token Variable	✅	The variable name where the resulting data will be stored.

Security Requirement

Always store your Client Secret in the project's Secrets configuration. Never hardcode it as a plain string in the block.

Output

Once executed, the block stores a JSON object in your specified variable:

{
  "tokens": {
    "access_token": "gho_16characters...",
    "scope": "read:user,user:email",
    "token_type": "bearer"
  },
  "user": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "name": "monalisa octocat",
    "email": "[email protected]"
  }
}

You can access specific fields using dot notation:

{github_auth.user.login}
{github_auth.tokens.access_token}

Error Handling

MISSING_CLIENT_ID — The Client ID field is empty.
MISSING_CLIENT_SECRET — The Client Secret selection is empty.
MISSING_REDIRECT_URI — The Redirect URI is missing.
MISSING_CODE — No authorization code was provided.
SECRET_RETRIEVE_ERROR — Failed to retrieve the secret from storage.
INVALID_CODE — The authorization code is invalid or has already been used.
INVALID_CLIENT — Client authentication failed (check your Client Secret).
INVALID_REDIRECT_URI — The Redirect URI does not match the one registered in GitHub.
INVALID_REQUEST — The request is missing a required parameter.
USER_FETCH_ERROR — Failed to retrieve the user profile after token exchange.
RUNTIME_ERROR — An unexpected error occurred.

Example

User Login: Redirect your user to GitHub's Auth URL.
Callback: GitHub redirects to your endpoint: https://app.com/api/github/callback?code=gh_code_123.
Exchange: Use this block to process the code:
- Authorization Code: {request.query.code}
- Token Variable: gh_exchange
Result: You now have {gh_exchange.user.avatar_url} to display the user's profile picture.

GitHub OAuth2 Exchange

Configuration

Output

Error Handling

Example

Other OAuth Providers

Google OAuth2

Discord OAuth2

Microsoft OAuth2

On this page