alter connect

A Connect session is the page an end user opens to authorize a provider, or, for a managed secret, to enter their own key or approve the one they hold. create is a runtime call: it signs with the application’s runtime key from ALTER_API_KEY (or --api-key), not a PAT, and the key already names the application.

alter connect create --provider <provider-id> [--user-token <jwt> --agent <agent>] [--delegable] [--return-url <url>] [--tag <key=value>]
alter connect create --secret <slug> --user-token <jwt> [--agent <agent>] [--delegable] [--return-url <url>] [--tag <key=value>]

create

Flag	Required	Description
--provider <provider-id>	one of these two	The OAuth provider to connect.
--secret <slug>	one of these two	The managed-secret provider’s slug. Requires --user-token.
--user-token <jwt>	with --secret or --agent	The end user’s IDP JWT: a managed-secret session is bound to a user, and a delegation needs the user consenting to it. Pass it through a variable (--user-token "$USER_JWT") so it stays out of shell history.
--agent <agent>	no	Agent id or name the end user delegates the connection to. Requires --user-token.
--delegable	no	Ask the end user to let that agent delegate onward. Requires --agent.
--return-url <url>	no	Where to send the browser afterwards, instead of a popup message.
--tag <key=value>	no	Tag each grant the session creates (repeatable). A grant it reuses is unchanged. A delegation it creates starts from its parent’s tags; --tag only adds keys and cannot change a tag the parent passes down.
--api-key <key>	no	The application’s runtime key. Prefer ALTER_API_KEY.
--output <format>	no	json (default).

The output is the session as JSON. Open the connect_url field in a browser; the session_token field is the same session for the Connect widget. expires_in and expires_at say how long it lasts. Warnings about a provider the agent’s allowlist cannot use go to stderr, leaving stdout a clean JSON object.

alter connect create --provider google --user-token "$USER_JWT" --agent worker --delegable --tag client=vc --output json
alter connect create --secret stripe --user-token "$USER_JWT" --tag client=vc --output json

Related

• alter grants delegate hands a delegated grant on to another agent.
• Give an agent scoped access explains delegation.