Skip to content
API Reference
GitHub logo

GitHub

Developer Tools

Access repositories, issues, and pull requests

Adding GitHub provisions a resource (the upstream GitHub API at https://api.github.com, with default scopes pre-set) and a provider for GitHub’s OAuth issuer - auto-provisioned on first install, or reused if you already connected another GitHub resource.

Your application calls Keycard’s token-exchange endpoint with the user’s identity, gets back a token scoped to this resource, and uses it to call GitHub directly. Identity, policy, and audit log apply to every exchange - the OAuth client secret stays inside Keycard. Each exchange is recorded in the audit log with the user identity, the resource accessed, and the policy decision.

Call GitHub from your application with a Keycard-issued token scoped to this resource.

After installing GitHub, your application exchanges a Keycard-issued access token for a token scoped to this resource. Pass the user’s access token as the subject_token.

from keycardai.oauth import Client, BasicAuth, TokenType
import requests
# Exchange the user's Keycard token for a GitHub token.
with Client(
"https://<zone-id>.keycard.cloud",
auth=BasicAuth("<your-client-id>", "<your-client-secret>"),
) as client:
response = client.exchange_token(
subject_token=user_access_token,
subject_token_type=TokenType.ACCESS_TOKEN,
resource="https://api.github.com",
)
# Call GitHub directly with the exchanged token.
r = requests.get(
"https://api.github.com/<endpoint>",
headers={"Authorization": f"Bearer {response.access_token}"},
)

See the OAuth SDK → Token Exchange reference for the full client API.

Register your OAuth credentials with Keycard so the resource can issue tokens.

  1. Go to GitHub App Settings
  2. Click New GitHub App
  3. Fill in:
    • GitHub App name: A descriptive name (e.g., “Keycard”)
    • Homepage URL: Your application URL (e.g., http://localhost:3000)
    • Callback URL: The redirect URI provided by Keycard
  4. Under Permissions, select the permissions your app needs (e.g., RepositoryContents: Read-only)
  5. Click Create GitHub App
  1. On the app page, note the Client ID
  2. Click Generate a new client secret
  3. Copy the Client Secret immediately (it’s only shown once)
  1. Open Keycard Console → your zone → Resources
  2. Click Explore Resources
  3. Find and click GitHub in the catalog
  4. In the configuration dialog, enter the Client ID and Client Secret from your GitHub App
  5. Click Add GitHub API

Common errors when wiring GitHub into your zone.

Error 401: Bad credentials

The access token is invalid or expired. Try re-connecting the provider in Keycard Console. If the issue persists, verify the client credentials in Keycard Console match the ones in GitHub Developer Settings.

Error: redirect_uri mismatch

GitHub requires the callback URL to match exactly. Copy the redirect URI from Keycard Console and paste it as the Authorization callback URL in GitHub.