alter providers

Each app configures the OAuth providers its users can connect. These commands manage those per-app provider configs, and browse the provider API spec store — every provider’s active API spec, its operations, and each operation’s schemas.

alter providers list-catalog
alter providers list
alter providers create  --provider <id> --scopes <list> --client-id ... --client-secret ... --redirect-uri ... [--redirect-uri-alias <name>]
alter providers show    --provider <id>
alter providers update  --provider <id> [--scopes ...] [--status ...] [...]
alter providers set-delegation-policy --provider <id> [--delegable | --no-delegable] [--max-delegation-depth <1-8>]
alter providers delete  --provider <id> [--force] [--confirm <id>]
alter providers spec list       [--kind oauth|managed]
alter providers spec status     <provider> [--kind oauth|managed]
alter providers operations list <provider> [--kind oauth|managed] [--search <q>] [--limit <n>] [--offset <n>]
alter providers operations get  <provider> <operation-id> [--kind oauth|managed]

App-scoped commands take --app <id> (or the app’s name), or link a workspace / set ALTER_APP_ID. Reads (list / show) need dashboard_providers:read; create / update / set-delegation-policy need dashboard_providers:write; delete needs the explicit, wildcard-excluded dashboard_providers:delete scope. list-catalog has no scope requirement, but the CLI still requires a signed-in PAT to construct its configured client. create also accepts the alias configure.

The spec-store reads (spec ... / operations ...) take no --app and need no particular scope — any signed-in token can browse them, since API specs are public provider documentation data.

list-catalog

List the catalog of supported OAuth providers — the set that can be configured for any app. This is the global catalog, not the per-app config, so it needs no --app. The MANAGED column reports whether this deployment currently has an Alter-managed OAuth app available. MANAGED SCOPES reports its exact approved scope set; JSON output carries managed_credentials_available and managed_approved_scopes. Use these live fields instead of a hardcoded provider or scope list.

The REDIRECT ALIAS column names providers that take a provider-issued redirect name as redirect_uri instead of the callback URL, using the provider’s own term for it (eBay: RuName); JSON output carries redirect_uri_alias as { "label", "description" }, or null for every other provider. Configuring such a provider with custom credentials requires --redirect-uri-alias on create, and on an update that switches the config to custom credentials.

alter providers list-catalog

list

List the providers configured for an app, with grant counts, status, and the current verdict for starting new authorization flows. Alter-managed (shared_dev) rows include new_authorization_available and, when blocked, a provider-specific new_authorization_unavailable_reason. Existing grants remain usable when new authorization is unavailable. The REDIRECT ALIAS column (JSON: redirect_uri_alias) shows the provider-issued redirect name a config sends as redirect_uri; it is empty (JSON null) unless the provider uses one and the config uses custom credentials. An Alter-managed (shared_dev) config carries the name on the shared credential, so its row shows none. The ONWARD column shows the provider’s agent sharing (see set-delegation-policy): off, or on (≤N) where N is how many agents deep a chain may go. With a depth of 1 an agent holds the access but cannot share it onward, so the column reads on (≤1, no onward hop). JSON output carries it as delegation_policy.

The command returns the server’s first page (up to 100 provider configs) as an array; it does not expose pagination flags.

alter providers list

create

Configure a provider for the app.

Flag	Required	Description
--provider <id>	yes	Provider ID (e.g. google, slack, github).
--scopes <list>	for providers with selectable scopes	Comma-separated provider scopes (e.g. email,profile). At least one is required when the provider publishes selectable scopes. Omit the flag for scopeless providers (for example Notion or Zoom) — they take no scope selection, and supplying one is rejected.
--credential-source <source>	no	custom (default) or shared_dev (Alter-managed). shared_dev is a legacy wire name, not an Alter-app environment restriction. Confirm availability and the exact managed_approved_scopes with list-catalog; managed credentials use Alter’s consent branding, callbacks, and shared provider quota. App-owned client IDs, secrets, and redirect URIs are rejected in this mode. Before saving, the CLI queries live Alter-managed credential availability and reports the provider-specific reason when new authorization is unavailable.
--client-id <id>	when --credential-source custom (the default)	OAuth client ID.
--client-secret <value>	when --credential-source custom (the default)	OAuth client secret. Use - to read from stdin or @/path/to/file; an inline value prints a shell-history warning.
--environment <env>	no	production (default) or sandbox. The CLI checks the provider catalog and accepts sandbox only when the selected provider publishes it (currently PayPal). shared_dev credentials are production-only. A sandbox credential is not valid against production endpoints, or the reverse; the save-time credential check probes the selected environment’s real endpoint and rejects a credential that belongs to the other deployment.
--redirect-uri <uri>	when --credential-source custom (the default) — at least one	Add a valid HTTP or HTTPS redirect URI. Repeatable, or comma-separated; both forms accumulate.
--redirect-uri-alias <name>	for providers that use one, with --credential-source custom	The provider-issued redirect name sent as redirect_uri in place of the callback URL (eBay’s RuName). Required for a provider whose list-catalog row shows a REDIRECT ALIAS label, and rejected for every other provider and for shared_dev credentials; the CLI checks the catalog before saving. 1–255 characters.
--skip-preflight	no	Save without the provider credential check (audited; use only when the provider endpoint is unavailable). The response’s preflight summary reports skipped so the unverified state is never silent.
--input <path>	no	JSON body from a file (@path) or stdin (-); replaces the per-field flags, including --environment and --redirect-uri-alias (body key redirect_uri_alias). Non-default per-field values supplied alongside it are ignored with a warning.

alter providers create \
  --provider google \
  --scopes openid,email,https://www.googleapis.com/auth/calendar.readonly \
  --client-id <google-client-id> \
  --client-secret @/run/secrets/google \
  --redirect-uri https://app.example.com/oauth/callback

Note

Provider-specific required scopes (for example, Google’s openid) are enforced when the config is saved. Consult the provider’s own documentation for its scope vocabulary.

Warning

For Slack, --scopes configures Bot Token Scopes. Alter sends them through Slack’s OAuth scope parameter and stores the resulting bot token (xoxb-... without rotation, xoxe.xoxb-... with rotation); it does not request user_scope. Add the same scopes under OAuth & Permissions → Bot Token Scopes in your Slack app. With chat:write, invite the app to each destination channel; add chat:write.public only when it should post to any public channel without joining. The latter depends on chat:write, and the CLI rejects either flag or --input bodies that omit that prerequisite.

Use shared_dev when the catalog reports managed credentials and Alter’s branding, reported approved scope set, shared quota, and production provider deployment fit. Use custom for custom consent branding or scopes, dedicated quota, a sandbox or custom provider deployment, or your own provider review. See Credentials managed by Alter.

Redirect-URI alias (eBay’s RuName)

Most providers accept the callback URL itself as redirect_uri. eBay does not: the callback URL is registered in the eBay developer console as the Auth Accepted URL (under User Tokens), the console assigns it a RuName (Redirect URL name, for example Davy_Developer-DavyDeve-DavysT-euiukxwt; eBay issues one per environment, and Alter uses the production one), and eBay requires that name, never the URL, in every consent request and token exchange. With the URL in its place eBay rejects the request before any consent screen, so an eBay config without its RuName can never mint a grant.

alter providers list-catalog shows which providers work this way in the REDIRECT ALIAS column. For those providers, create with custom credentials requires --redirect-uri-alias; the CLI checks the catalog and fails locally with exit code 2, naming the provider’s own term and where the value comes from, before anything is saved. An update that switches such a config from shared_dev to custom credentials requires it the same way: the CLI reads the stored config and refuses the switch locally unless a RuName is already stored or supplied. Supplying the flag for a provider that does not use one fails the same way (--redirect-uri-alias is not used by <provider>), as does combining it with shared_dev credentials, on create and update alike. The value is trimmed and must be 1–255 characters, whether it comes from the flag or from the redirect_uri_alias key of an --input body. The stored value is returned as redirect_uri_alias by create, show, list, and update (null for an Alter-managed config, which carries the name on the shared credential); --redirect-uri keeps its meaning (it is the URL registered under the name).

alter providers create \
  --provider ebay \
  --scopes https://api.ebay.com/oauth/api_scope,https://api.ebay.com/oauth/api_scope/commerce.identity.readonly \
  --client-id <ebay-app-id> \
  --client-secret @/run/secrets/ebay \
  --redirect-uri https://app.example.com/oauth/callback \
  --redirect-uri-alias <ebay-runame>

Credential preflight

When custom credentials are created or changed, the CLI prints the save-time provider check on stderr:

• passed — the credential was accepted.
• inconclusive — verification could not complete; the save was allowed.
• partial failure — part of the credential/redirect check failed; the save was allowed, but both credentials and redirect registration need review.
• skipped — the credentials were not verified.

A definitive credential rejection fails the save. Breaking-change and other safe warning details returned by an update are also printed on stderr so JSON stdout remains pipeable.

show

Shows the provider config. The client secret is never returned. Alter-managed configs include new_authorization_available and, when blocked, new_authorization_unavailable_reason; these describe fresh authorization only, not the usability of existing grants. redirect_uri_alias is the provider-issued redirect name the config sends as redirect_uri (null unless the provider uses one and the config uses custom credentials; an Alter-managed config carries the name on the shared credential). delegation_policy is the provider’s agent sharing, { "delegable", "max_delegation_depth" } (see set-delegation-policy).

alter providers show --provider google

update

Patch a provider config. Every field is optional; only what you pass changes. Narrowing the scope set is a breaking change, and the response lists any breaking changes it detected.

Flag	Description
--credential-source <source>	custom or shared_dev (Alter-managed). Check list-catalog first. shared_dev is production-only: switching to it while the stored environment is sandbox is rejected unless the same update also passes --environment production (and the reverse — re-pointing a shared_dev config at sandbox — requires switching to custom credentials in the same update). The CLI also checks managed-credential availability before switching and reports the provider-specific reason when unavailable. Changing source switches the OAuth client and requires every existing user to reconnect.
--client-id <id>	New client ID. Changing it requires every existing user to reconnect; resaving the same ID is a no-op for connection health.
--client-secret <value>	New client secret (- for stdin, @file for a file); an inline value prints a shell-history warning.
--environment <env>	Re-point the config at another deployment: production or sandbox. Omit to leave it unchanged. Accepted only when the provider publishes the target environment (the CLI checks the catalog first), and shared_dev credentials are production-only. Breaking — see below.
--scopes <list>	New provider scopes (comma-separated).
--redirect-uri <uri>	Replace redirect URIs with valid HTTP or HTTPS URLs (repeatable or comma-separated).
--redirect-uri-alias <name>	Replace the provider-issued redirect name sent as redirect_uri (eBay’s RuName). Omit to leave it unchanged. Accepted only for a provider whose list-catalog row shows a REDIRECT ALIAS label, on custom credentials; the CLI refuses it locally for any other provider and with --credential-source shared_dev. Required when --credential-source custom switches an Alter-managed config to custom credentials (the CLI checks the stored config first). 1–255 characters.
--status <status>	active or disabled.
--skip-preflight	Save without the provider credential check (audited; use only when the provider endpoint is unavailable). The response’s preflight summary reports skipped so the unverified state is never silent.
--input <path>	JSON body from a file (@path) or stdin (-); replaces the per-field flags, including --environment and --redirect-uri-alias (body key redirect_uri_alias).

alter providers update --provider google --status disabled

Changing the OAuth client

Changing --credential-source or replacing the custom --client-id changes the provider OAuth client. Existing access and refresh tokens remain bound to the client that issued them, so the backend marks every active connection reconnect-required, clears its refresh schedule, and reports the count in breaking_changes. Every user must complete fresh consent before the connection can be used again. Rotating --client-secret for the same client ID does not require user reconnection.

Moving between environments

Changing --environment invalidates every existing grant for that provider: the stored tokens were issued by the deployment being left and are not valid against the new one, so every connection is marked reconnect-required and all users must reconnect. After a committed change the response lists this in breaking_changes, which the CLI surfaces on stderr — passing the currently stored environment is a no-op and reports nothing.

Sandbox and live credentials are not interchangeable, so change them in the same call:

alter providers update --provider paypal \
  --environment production \
  --client-id <live-client-id> --client-secret -

set-delegation-policy

Set the provider’s agent sharing: whether an agent that holds a user’s access to this provider may share it with other agents, and how many agents deep a chain may go. When sharing is on, the user still decides on the consent screen whether their agent may share it; when it is off, every onward share is refused. A provider configured after agent sharing was introduced starts with sharing off; a provider configured before it reads on at depth 8, so existing apps keep working. Agent sharing cannot be set by create; use this command (or the dashboard’s Agent sharing card) once the provider exists.

Flag	Description
--provider <provider>	Provider ID. Required.
--delegable	Turn agent sharing on.
--no-delegable	Turn agent sharing off. Mutually exclusive with --delegable.
--max-delegation-depth <n>	How many agents deep a chain may go, counting the user’s own agent as 1: a whole number from 1 to 8. 1 means that agent cannot share it onward.
--output <format>	json (default), jsonl, or table.

Pass at least one of --delegable, --no-delegable, and --max-delegation-depth. The command sends only the flags passed, and Alter keeps the stored value of the other one, so it never turns sharing off, or resets the depth, by omission, and two operators changing different settings at the same time do not undo each other. The CLI refuses conflicting flags, a run with nothing to change, and a depth outside 1–8 with a usage error (exit 2) before sending anything — the same checks the dashboard’s dialog makes. The depth can be set while sharing is off (alone, or together with --no-delegable): it is stored, and applies once sharing is turned on. The dashboard’s dialog locks the depth field while sharing is off; the CLI and the API accept it. The command prints the updated provider config; its delegation_policy field is the stored policy. It runs no credential preflight and works on a disabled provider. The managed-secret counterpart is alter managed-secrets set-delegation-policy.

# Let agents share GitHub access, at most 3 agents deep
alter providers set-delegation-policy --provider github --delegable --max-delegation-depth 3

# Change only the depth (sharing stays as it is)
alter providers set-delegation-policy --provider github --max-delegation-depth 2

# Turn agent sharing off (the depth is kept)
alter providers set-delegation-policy --provider github --no-delegable

delete

Remove a provider config. This is an irreversible cascade: it destroys stored credentials, grants, and provider policy rows. Reconfiguring the provider does not reconstruct those resources. The backend and CLI require the exact provider ID as a type-to-confirm value.

--force deletes even when active grants exist. Those grants are deleted as part of the same irreversible cascade; they are not left orphaned. Affected users must reconnect through Alter Connect to obtain new grants.

In an interactive terminal, type the provider ID at the prompt. In CI or any non-interactive environment, pass --confirm <id> explicitly. A dashboard_providers:delete-only PAT can use the explicit form without needing read scope.

alter providers delete --provider google --confirm google

spec list

List every provider’s active API spec metadata — family, version, provenance, operation count, and when it was last fetched. This is the spec store’s freshness dashboard: use it to see which providers have operation data available and how current it is.

Flag	Required	Description
--kind <kind>	no	Filter by provider family: oauth or managed.

alter providers spec list
alter providers spec list --kind managed

spec status

Show one provider’s active spec metadata — version, provenance, operation count, and fetch freshness.

Flag	Required	Description
--kind <kind>	only for dual-family ids	oauth or managed. A few provider ids (for example github and stripe) have specs in both families; for those, pass --kind to pick one. Otherwise it is resolved automatically.

alter providers spec status <provider>
alter providers spec status github --kind oauth

operations list

Page through one provider’s API operations from its active spec — the operation id, HTTP method, path, and summary for each. Agents and scripts use this to discover what calls a provider supports without leaving the terminal.

Flag	Required	Description
--kind <kind>	only for dual-family ids	oauth or managed — same resolution rules as spec status.
--search <q>	no	Filter over operation id, method, path, and summary.
--limit <n>	no	Page size, 1–500 (default 100).
--offset <n>	no	Page offset. When more pages remain, the CLI prints the next --offset to use on stderr.

alter providers operations list <provider> --search messages
alter providers operations list github --kind oauth --limit 50 --offset 50

operations get

Show one operation in full — including its parameter, request-body, and response schemas — plus the spec metadata it came from.

Flag	Required	Description
--kind <kind>	only for dual-family ids	oauth or managed — same resolution rules as spec status.

The operation id is positional and opaque, exactly as listed by alter providers operations list. Reserved characters and slashes are supported; empty or over-512-character ids are rejected locally.

alter providers operations get <provider> <operation-id>
alter providers operations get github repos/get
alter providers operations get google gmail.users.messages.list --kind oauth

Recipes

Configure a provider with the secret read from a file (CI-safe)

alter providers create \
  --provider google \
  --scopes openid,email \
  --client-id <google-client-id> \
  --client-secret @/run/secrets/google \
  --redirect-uri https://app.example.com/oauth/callback

Temporarily disable a provider, then re-enable it

alter providers update --provider google --status disabled
# ...later...
alter providers update --provider google --status active

Related

• alter managed-secrets — non-OAuth backend credentials
• Provider discovery — the operation catalog the spec / operations commands browse
• Providers, Connections