Quickstart

By the end of this quickstart, an app key will be minted, Google Calendar will be connected, and upcoming events will be read from application code — with no token ever touching that code.

Total time: about 10 minutes.

Note

This quickstart uses Google Calendar because Alter-managed Google credentials let a development app reach the real consent flow without first creating a provider-console OAuth app. Any configured OAuth provider in the provider catalog follows the same Connect and proxy flow, but provider-console setup and Alter-managed credential availability differ by provider.

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.

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+.

Add Google Calendar

Open OAuth Providers → Add Provider → Google. Confirm the Managed credentials available badge, keep the Alter-managed credential option, and select these scopes:

• openid
• email
• profile
• https://www.googleapis.com/auth/calendar.readonly

Click Save. There is no Google Cloud Console setup for this development quickstart. Before production, replace the development credential with your own verified Google OAuth client using the Google setup guide.

Connect Google

Run the snippet below once. It opens a browser, walks through Google consent, 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=["google"])
        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: ["google"] });
  console.log("grantId:", results[0].grantId);
} finally {
  await app.close();
}

Export the printed grant ID:

export GOOGLE_GRANT_ID="<the printed grant id>"

List upcoming calendar events

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://www.googleapis.com/calendar/v3/calendars/primary/events",
            grant_id=os.environ["GOOGLE_GRANT_ID"],
            query_params={"maxResults": 5, "singleEvents": True},
        )
        events = response.json().get("items", [])
        print(response.status_code, [event.get("summary", "Untitled") for event in events])

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://www.googleapis.com/calendar/v3/calendars/primary/events",
    {
      grantId: process.env.GOOGLE_GRANT_ID!,
      queryParams: { maxResults: 5, singleEvents: true },
    },
  );
  const body = (await response.json()) as { items?: Array<{ summary?: string }> };
  console.log(response.status, body.items?.map((event) => event.summary ?? "Untitled") ?? []);
} finally {
  await app.close();
}

The response lists up to five events from the connected account’s primary calendar.

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 Google grant, fetched a fresh token from the vault, injected it into the outgoing Google Calendar 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.