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 authenticated request 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 to the same result by a different route: instead of the portal clicks below, it runs the Alter CLI, wires the SDK, and checks each stage with the CLI’s 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.

Before you start

• A language runtime: Python 3.11+ or Node 20+.
• A Google account with a calendar. You connect it in Connect Google, and the quickstart then reads its upcoming events.
• A browser for Google consent. On a machine without one (over SSH, for example), the script prints the consent URL instead; open it in any browser.
• One terminal for the whole quickstart. Mint an API key and Save the grant ID export values that later steps read, and an export lasts only for the shell it ran in.

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 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 value you copied starts with alter_rk_, the prefix for app runtime keys. Alter keeps only a hash of it, so this is the only time you can copy it. Keep it out of source code and chat logs; see Your Credentials for where each Alter credential belongs.

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
npm install --save-dev tsx

Python 3.11+. Node 20+.

To run the snippets in the next steps, save each one to its own file:

• Python: save it as a .py file (for example, connect.py) and run python connect.py.
• TypeScript: save it with the .mts extension (for example, connect.mts) and run npx tsx connect.mts. The snippets use top-level await, which only works in an ES module; the .mts extension makes the file one without changing your package.json. A plain .ts file fails with Top-level await is currently not supported with the "cjs" output format.

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. Google now appears in the app’s OAuth Providers list. 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 steps. If no browser opens, it prints Open this URL to authorize: … instead; open that URL in any browser. The script waits up to five minutes for you to finish consent.

Warning

Google will say the app is not verified. On the managed credential, the OAuth client belongs to Alter rather than to your organization, and Google shows a “Google hasn’t verified this app” interstitial for any client it has not completed verification for. Choose Advanced, then Go to alterauth.com (unsafe) to reach the consent screen.

Two things follow from that screen belonging to Alter: the consent page names Alter, not your product, and the warning is a property of the OAuth client, not of your app or this SDK. Both disappear once you replace the managed credential with your own verified Google OAuth client — the step above and the Google setup guide cover that, and it is required before production regardless.

Only continue past this screen for a client you recognise. Here that is Alter’s own, consenting your own Google account into your own development app.

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();
}

When consent finishes, the script prints one line and exits:

grant_id: 11111111-2222-3333-4444-555555555555

The TypeScript snippet prints grantId: instead. The ID is a UUID; yours will differ.

Save the grant ID

Export the printed grant ID in the same terminal that holds ALTER_API_KEY:

export GOOGLE_GRANT_ID="<the printed grant id>"

A grant is the stored, user-consented connection to one provider account. The next step passes its ID so Alter knows whose Google Calendar to call.

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. The script prints the HTTP status and the event titles, for example:

200 ['Team standup', 'Design review', 'Lunch with Sam']

An empty list with 200 is also a success; it means the calendar has no events for the request to return.

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

Behind the scenes, app.request() used retrieve mode: the SDK fetched the Google token from Alter, injected it into the outgoing Calendar call from the application process, and wrote the audit row. Application code only received the Calendar response. To keep the token in Alter’s backend, use proxy mode with app.proxy_request() instead.

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.