Admin

Setting Up an App

Create an app, configure providers, mint API keys.

An app is the unit that owns API keys, provider configuration, and grants. Most products have one app per environment (production, staging). This page covers the operator setup from zero to “the SDK can make calls.”

Creating the app

A brand-new workspace comes with a starter app named My First App — rename it from its settings and use it directly, or delete it. To create another app, open the Applications dashboard in the developer portal at portal.alterauth.com, select the Create application card, enter a name, and select Create Application.

For a multi-environment setup, create a separate app per environment (product-prod, product-staging). Each app has its own keys, grants, and provider configuration — no chance of a staging credential reaching production.

Configuring providers

Two kinds of providers, configured on different portal pages.

OAuth providers

For credentials end users authorize themselves (Google, Slack, GitHub, …):

Open the app and select OAuth in the sidebar. On the OAuth Providers page, select Add Provider.
Pick the provider from the catalog (or Custom OAuth for anything not listed).
If the card shows Managed credentials available, choose whether to use Alter’s OAuth app or your own. Managed credentials require no provider console setup and use Alter’s consent branding, callback URLs, exact provider-approved scope set, and shared quota. The portal and catalog expose that set; they never infer it from every scope the provider supports. Managed credentials are available to any Alter app despite the legacy shared_dev API name.
For your own OAuth app, follow the per-provider instructions to register a client, add Alter’s redirect URI to its allowed callbacks, and paste the Client ID and Client Secret into Alter.
Pick the scope set. In managed mode there is no provider console for you to update; switch to your own app for custom scopes, branding, dedicated quota, a sandbox/custom provider deployment, or your own provider review.

Switching an existing provider between Alter-managed and custom credentials — or replacing its custom client ID — marks every existing connection for reconnection. Provider tokens are bound to the OAuth client that issued them, so each user must complete fresh consent before the connection works again.

Each OAuth provider page has an Agent sharing card. It controls whether an agent that holds a user’s access to the provider may share it with other agents, and how many agents deep a chain may go (1–8, counting the user’s own agent as 1). Select Edit on the card to change it.

Off — an agent can use the access a user gave it, but cannot pass it on. A provider you configure starts with sharing off.
On — the user decides, when they connect, whether their agent may share the access, up to the depth you set. The user signs in through the app’s identity provider before choosing, so this needs the identity provider’s sign-in client (Client ID and Client Secret). Embedded Connect asks in the provider window, where the user can sign in. Without the sign-in client, or on a screen shown inside the embedded Connect frame (the approval step for an account the user already connected), the user is offered no choice: a new delegation cannot be shared onward, and an existing one keeps its setting.

A provider configured before agent sharing was introduced reads on at the full depth of 8, so existing apps keep working; turn it off if your app does not need it. The OAuth Providers list marks every provider that allows sharing with an Agents may share onward badge. From the CLI, use alter providers set-delegation-policy.

Discover the live managed-credential set with alter providers list-catalog; see Providers for the full decision guide and OAuth providers for provider-specific setup.

Managed-secret providers

For credentials the operator owns (Datadog API key, AWS access key, …):

Open the app, select Managed Secrets, then select Add Managed Secret.
Pick the provider from the catalog (or Custom for any header-based credential — see Connect a custom API).
Paste the credential. It’s encrypted and sent to the vault; the portal will not display it again.
Issue at least one grant binding the credential to a principal.

Full catalog: Managed secret providers reference.

Configuring the identity provider

If the app has logged-in end users, wire an identity provider so the SDK can resolve users from their JWTs. Identity providers are included on every plan. Skip this step for backend-only apps and operator scripts.

Open Branding to set the logo, colors and font the Connect consent screen shows the app’s end users. Branding requires a plan that includes custom branding (Starter and above); on a plan without it the editor is replaced by an upgrade prompt. Resetting to Alter’s default branding stays available on every plan, so an organization that downgrades can still clear branding it can no longer edit.

A hosted https:// logo is fetched when it is saved and the result is reported inline. The common mistake is pasting the address of a page showing the image rather than the image file itself: the part after # never reaches the server, so only the page is fetched. The save still goes through and the notice reports that the logo will not display. A destination resolving to a loopback, link-local, private or reserved network is rejected before the write so the consent screen cannot make an end user’s browser request that user’s network. Uploaded images skip the fetch; their format is validated on upload.

Fonts are fetched by Alter and served from Alter’s own origin, so no end user’s browser makes a request to a third-party font host.

The same settings are scriptable with alter branding.

Minting an API key

Open API Keys and select Create key. The plaintext (alter_rk_…) is shown once — copy it into a secret manager and revoke if it’s ever lost.

See API keys for rotation, per-agent keys, and scoped derivation.

Verifying

Run the Quickstart Google Calendar flow against the new app, or run any of the guides. Setup is complete only when the provider-specific response reports success. Do not rely on HTTP status alone: some providers, such as Slack, return HTTP 200 even when the JSON body contains {"ok": false, "error": "..."}.