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 ...
alter providers show    --provider <id>
alter providers update  --provider <id> [--scopes ...] [--status ...] [...]
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 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.

alter providers list-catalog

list

List the providers configured for an app, with grant counts and status.

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>	yes	Comma-separated provider scopes (e.g. email,profile). At least one is required.
--credential-source <source>	no	custom (default) or shared_dev.
--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.
--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. 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.

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 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.
--client-id <id>	New client ID.
--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).
--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.

alter providers update --provider google --status disabled

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 -

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