# GitHub user OAuth credentials

> Authorize GitHub once and create one renewable, principal-scoped Credential for each consenting user.

Use GitHub user OAuth when an agent must act as a specific person. The Constal-managed provider is available in every tenant and starts authorization directly from **Create credential**.

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

Know which principal or customer will own the grant and which GitHub operations the agent needs. No provider installation, Client ID, Client Secret, or callback configuration is required for the Constal-managed flow.

Constal uses a callback-bound state and PKCE proof. Access material is encrypted as the output Credential; refresh material remains encrypted provider-private state and is never exposed to the consuming GitHub Resource.

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).

## Authorize a user {#steps}

1. Select **Create credential** and choose **GitHub user OAuth**.
2. Name the Credential for the user or account.
3. Select **Continue**.
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 integration never receives the refresh token.

## Bring your own GitHub App {#bring-your-own}

Install the **GitHub user OAuth** package from the provider catalog only when downstream users must authorize a tenant-owned GitHub App. Configure that provider once with the App Client ID, encrypted Client Secret, exact callback URL, expiring user tokens, and least-privilege permissions. Do not install one provider per user.

## 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:** for a bring-your-own provider, 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).