Documentation / Credentials / Integrations

GitHub user OAuth credentials

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

how-toFor GitHub App owners, tenant administrators, application developersOwner Constal platform teamVerified 2026-08-20

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

  • 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 and User authorization callback URLs.

Set up the provider

  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

  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

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

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

  • 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

Read OAuth callback security, Scoped bindings, and Reconnect.