# GitHub user OAuth credentials

> Configure GitHub App user authorization and create one renewable Credential for each consenting user.

Use GitHub user OAuth when an agent must act as a specific person. This provider targets GitHub App user access tokens, not a legacy standalone OAuth App.

## Before you begin {#before-you-begin}

- Create or select the tenant-owned GitHub App.
- Enable expiring user access tokens and refresh tokens.
- Generate a Client Secret.
- Register `https://platform.constal.ai/v1/credential-authorizations/callback` as an exact callback URL.
- Configure only the permissions required by user-attributed operations.

The OAuth flow requires the GitHub App **Client ID**, which is different from the App ID, and the Client Secret. The secret is used server-side for code exchange, refresh, and revocation.

GitHub references: [Generating a user access token](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) and [User authorization callback URLs](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url).

## Set up the provider {#steps}

1. In **Credentials → Providers**, select **Add provider**.
2. Choose **GitHub user OAuth**.
3. Enter the GitHub App Client ID.
4. Paste the GitHub App Client Secret.
5. Copy the callback URL shown by Constal into the GitHub App settings.
6. Select **Set up provider**.

One provider instance can create many user Credentials. Do not install a new provider for every user.

## Authorize a user {#authorize-user}

1. Select **Create credential** and choose the installed GitHub user OAuth provider.
2. Name the Credential for the user or account.
3. Select **Continue to authorize**.
4. Review and approve the GitHub consent screen.

Constal stores the access token as Credential material and the refresh token as encrypted provider-private state. The consuming GitHub Driver never receives the refresh token.

## Bind it {#bind-it}

Use a principal-scoped Credential selector when the authenticated caller and GitHub grant belong to the same person:

```text
key github-user + principal Alice → credential/github-alice
key github-user + principal Bob   → credential/github-bob
```

Signing in to invoke an agent is a separate AuthProvider decision. Create this outbound Credential only after explicit consent for the agent to act on GitHub.

## Verify {#verify}

Confirm status is active and call a read-only `/user` operation through the GitHub Resource. Check that the correct principal-scoped binding was pinned into the run.

## Troubleshooting {#troubleshooting}

- **Incorrect client credentials:** verify the Client ID and Client Secret belong to the same GitHub App.
- **Redirect URI mismatch:** register the exact shared callback without extra query parameters.
- **No refresh token:** enable expiring user access tokens in the GitHub App.
- **Organization data unavailable:** confirm App permissions, installation access, organization approval, and the user's own access.

## Next steps {#next-steps}

Read [OAuth callback security](/docs/credentials/oauth/callback.md), [Scoped bindings](/docs/credentials/scoped-bindings.md), and [Reconnect](/docs/credentials/lifecycle.md#reconnect).