Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Connect your users to GitHub for repository management, issue tracking, pull requests, and code access.
PropertyValue
Provider IDgithub
PKCESupported
Token refreshNot needed (tokens don’t expire)
Access token lifetimeNever expires (revoked after 1 year of inactivity)
Redirect URIShown in Developer Portal
This guide covers GitHub OAuth Apps, not GitHub Apps. OAuth App tokens don’t expire, so there’s no refresh token flow.

​
Step 1: Create a GitHub OAuth App

1

Go to GitHub Developer Settings

Navigate to github.com/settings/developers and click OAuth Apps > New OAuth App.For organization-owned apps, go to Organization Settings > Developer settings > OAuth Apps.
2

Fill in app details

  • Application name: Your app name (e.g., “My App”)
  • Homepage URL: Your app’s URL (e.g., https://myapp.com)
  • Authorization callback URL: Copy the Redirect URI from the Developer Portal
  • Click Register application
3

Get your credentials

After creating the app:
  • Client ID: Displayed on the app page
  • Client Secret: Click Generate a new client secret and copy it immediately
The Client Secret is only shown once. Store it securely.
Copy your Client Secret immediately after generating it. GitHub only shows it once.

​
Step 2: Add to Alter Vault

1

Open the Developer Portal

Go to portal.alterauth.com and navigate to your app.
2

Add GitHub provider

Go to OAuth Providers > Add Provider > GitHub.
3

Enter credentials

  • Client ID: Paste your GitHub Client ID
  • Client Secret: Paste your GitHub Client Secret
4

Select scopes

Choose the scopes your app needs. See the Available Scopes section below.
5

Save

Click Save. The provider is now active.

​
Step 3: Test It

After a user connects via Alter Connect, use the returned grant_id to make API calls: 
from alter_sdk import AlterVault, HttpMethod

async with AlterVault(
    api_key="alter_key_...",
    caller="my-agent",
) as vault:
    response = await vault.request(
        HttpMethod.GET,
        "https://api.github.com/user/repos",
        grant_id=grant_id,
        query_params={"sort": "updated", "per_page": "5"},
    )
    repos = response.json()
    for repo in repos:
        print(f"{repo['name']} - {repo.get('description', 'No description')}")

​
Available Scopes

​
Repository

ScopeDescription
repoFull access to public and private repositories
public_repoAccess public repositories only
repo:statusAccess commit statuses
repo_deploymentAccess deployment statuses
repo:inviteAccept/decline repository invitations
delete_repoDelete repositories

​
User

ScopeDescription
userFull read/write access to profile (includes user:email and user:follow)
read:userRead-only access to profile data
user:emailRead email addresses
user:followFollow/unfollow users

​
Organization

ScopeDescription
admin:orgFull organization management
write:orgRead/write access to org membership and projects
read:orgRead-only access to org and team membership

​
Webhooks & Keys

ScopeDescription
admin:repo_hookFull access to repository hooks
admin:org_hookFull access to organization hooks
admin:public_keyFully manage public keys
admin:gpg_keyFully manage GPG keys

​
Other

ScopeDescription
gistWrite access to gists
notificationsAccess notifications
projectRead/write access to user and organization projects
workflowAdd and update GitHub Actions workflows
write:packagesUpload/publish packages
read:packagesDownload packages
codespaceCreate and manage Codespaces
GitHub automatically removes redundant scopes. For example, repo already includes public_repo and repo:status.

​
Common API Endpoints

Use CaseMethodURL
List user’s reposGEThttps://api.github.com/user/repos
Get a repositoryGEThttps://api.github.com/repos/{owner}/{repo}
List issuesGEThttps://api.github.com/repos/{owner}/{repo}/issues
Create an issuePOSThttps://api.github.com/repos/{owner}/{repo}/issues
List pull requestsGEThttps://api.github.com/repos/{owner}/{repo}/pulls
Get authenticated userGEThttps://api.github.com/user

​
Notes

  • GitHub OAuth App tokens never expire but are revoked after 1 year of inactivity. There’s no refresh token flow.
  • GitHub requires the Accept: application/json header for JSON responses from the token endpoint. Alter Vault handles this automatically.
  • If the user’s email is not public, Alter Vault automatically fetches it via the /user/emails endpoint (requires user:email scope).
  • GitHub’s API requires the X-GitHub-Api-Version header. When making calls via Alter Vault, you can add it via extra_headers if needed, though most endpoints work without it.