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.
Use GitHub from your code
Section titled “Use GitHub from your code”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, TokenTypeimport 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}"},)import { TokenExchangeClient } from "@keycardai/oauth/tokenExchange";
const client = new TokenExchangeClient("https://<zone-id>.keycard.cloud", { clientId: "<your-client-id>", clientSecret: "<your-client-secret>",});
const response = await client.exchangeToken({ subjectToken: userAccessToken, resource: "https://api.github.com",});
// Call GitHub directly with the exchanged token.const res = await fetch("https://api.github.com/<endpoint>", { headers: { Authorization: `Bearer ${response.accessToken}` },});See the OAuth SDK → Token Exchange reference for the full client API.
Register your OAuth credentials with Keycard so the resource can issue tokens.
Create a GitHub App
Section titled “Create a GitHub App”- Go to GitHub App Settings
- Click New GitHub App
- 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
- Under Permissions, select the permissions your app needs (e.g., Repository → Contents: Read-only)
- Click Create GitHub App
Get credentials
Section titled “Get credentials”- On the app page, note the Client ID
- Click Generate a new client secret
- Copy the Client Secret immediately (it’s only shown once)
Register in Keycard
Section titled “Register in Keycard”- Open Keycard Console → your zone → Resources
- Click Explore Resources
- Find and click GitHub in the catalog
- In the configuration dialog, enter the Client ID and Client Secret from your GitHub App
- Click Add GitHub API
Troubleshooting
Section titled “Troubleshooting”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.
Related
Section titled “Related”- Catalog overview - browse other API and MCP servers
- Access policies - control who can use GitHub
- Identity providers - control who can sign in