Quickstart

By the end of this quickstart, an app key will be minted, GitHub will be connected, and the signed-in profile will be read from application code — with no token ever touching that code.

Total time: about 10 minutes.

Note

This quickstart uses GitHub’s read-only authenticated-user endpoint. Any configured OAuth provider in the provider catalog follows the same flow — only the provider scopes and API call at the end change.

Tip

Using a coding agent? Connect the Alter Docs MCP server and it will walk your agent through this end to end — classifying the use case, running the CLI steps, wiring the SDK, and checking the verification gates:

claude mcp add --transport http alter-onboarding https://mcp.alterauth.com/mcp

It is public, unauthenticated, and read-only: it holds no credentials and cannot change anything in your account. See Alter Docs MCP Server for Cursor and other clients.

Sign up

Create a free account at portal.alterauth.com — sign up with Google single sign-on or with an email and password.

Open your app

New workspaces start with an app named My First App, ready to use — open it from the dashboard, or rename it from its settings. To start fresh instead, choose Apps → New App, name it quickstart, and click Create.

An app is the unit that owns API keys, provider configuration, and grants. See Apps & Organizations for the full model.

Configure GitHub

Open OAuth Providers → Add Provider → GitHub and copy the callback URL shown by Alter. In GitHub Developer Settings, register an OAuth app with that callback URL, then paste its Client ID and Client Secret into Alter. Select the read-only read:user scope and save.

The OAuth app belongs to the GitHub account or organization that registered it; the person completing Connect authorizes their own GitHub account. The GitHub provider guide has screenshots and production setup details.

Mint an API key

Open the new app, go to API Keys → Create key, choose the Backend service template, create the key, copy its one-time value, and export it:

export ALTER_API_KEY="alter_rk_..."

The template includes provider discovery, OAuth Connect, both runtime call modes, grant listing, and direct-call audit reporting. In particular, OAuth Connect needs both connect:initiate and grants:write; selecting only one cannot create a grant. The plaintext is shown once. If lost, create a new key and revoke the old one.

Install the SDK

pip install alter-sdk

npm install @alter-ai/alter-sdk

Python 3.11+. Node 20+.

Connect GitHub

Run the snippet below once. It opens a browser, walks through the GitHub OAuth flow, and prints the grant_id used in the next step.

import asyncio, os
from alter_sdk import App

async def main():
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        results = await app.connect(providers=["github"])
        print("grant_id:", results[0].grant_id)

asyncio.run(main())

import { App } from "@alter-ai/alter-sdk";

const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
  const results = await app.connect({ providers: ["github"] });
  console.log("grantId:", results[0].grantId);
} finally {
  await app.close();
}

Export the printed grant ID:

export GITHUB_GRANT_ID="<the printed grant id>"

Read the connected GitHub profile

import asyncio, os
from alter_sdk import App, HttpMethod

async def main():
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        response = await app.request(
            HttpMethod.GET,
            "https://api.github.com/user",
            grant_id=os.environ["GITHUB_GRANT_ID"],
            reason="Complete the Alter quickstart",
        )
        print(response.status_code, response.json())

asyncio.run(main())

import { App, HttpMethod } from "@alter-ai/alter-sdk";

const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
  const response = await app.request(
    HttpMethod.GET,
    "https://api.github.com/user",
    {
      grantId: process.env.GITHUB_GRANT_ID!,
      reason: "Complete the Alter quickstart",
    },
  );
  console.log(response.status, await response.json());
} finally {
  await app.close();
}

The response contains the profile fields authorized in the GitHub consent screen.

See the audit row

Open Audit Logs in the portal. Every Alter call shows the caller, the principal, the provider, the response status, and the latency.

What just happened

app.request() resolved the GitHub grant, fetched a fresh token from the vault, injected it into the outgoing GitHub call, and wrote the audit row. No token was ever stored, refreshed, or seen by application code.

What’s next

How Alter works

The mental model behind the call sequence above.

Call APIs on behalf of users

Drop the grant_id and resolve users from JWTs in production.

Give an agent scoped access

Per-agent identity for AI workloads.