alter sdk-passthrough

sdk-passthrough is an escape hatch for making one-off runtime SDK calls — the kind of thing you’d otherwise do with the runtime SDK’s request() or resolveIdentity(). It exists for debugging (“fetch a token for this grant and hit the provider once to see what comes back”, “which identity does the backend resolve for this key?”), deliberately namespaced so it reads as “I’m doing something unusual” rather than blending in with the management commands.

alter sdk-passthrough request <grant-id> --url <url> [--method ...] [--body ...] [--header ...] [--api-key <key>]
alter sdk-passthrough resolve-identity [--user-token <jwt>] [--app-user-id <uuid>] [--include-profile] [--api-key <key>]

Note

This is the one CLI command that does not use the PAT. It signs the request with a runtime API key — pass it via the ALTER_API_KEY environment variable (preferred) or --api-key. The PAT from alter auth login does not work here. Mint a runtime key with alter keys mint.

For anything beyond one-off debugging, use the Python or TypeScript SDK in application code.

request

Make a single authenticated call against a grant. The grant must be active and owned by the calling app.

Flag	Required	Description
--url <url>	yes	The full provider URL to call (e.g. https://www.googleapis.com/oauth2/v3/userinfo). Must be http:// or https://. There is no relative-path resolution — pass the complete URL.
--method <method>	no	HTTP method (default GET). One of GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.
--body <json>	no	JSON request body, passed verbatim to the provider.
--header <kv>	no	Extra header in Name: value form. Repeatable. Reserved headers (the Authorization header and Alter’s own request headers) are rejected — Alter injects the credential for you.
--api-key <key>	no	Runtime API key, if not using ALTER_API_KEY. Accepts any runtime key minted from the dashboard or CLI — alter_rk_…, alter_ak_…, alter_dk_…, alter_pk_…, or the legacy alter_key_…. PAT plaintext (alter_pat_…) is rejected — use alter auth login for that. Inline values print a shell-history warning.

The response body goes to stdout (pipe it into jq); the status line and response headers go to stderr, so the body stays clean for downstream tools.

export ALTER_API_KEY="alter_rk_..."

alter sdk-passthrough request <grant-id> \
  --url https://www.googleapis.com/oauth2/v3/userinfo \
  | jq .

# With a body
alter sdk-passthrough request <grant-id> \
  --method POST \
  --url https://slack.com/api/chat.postMessage \
  --body '{"channel":"#general","text":"hello"}'

resolve-identity

Resolve the canonical identity context for the runtime key (the SDK’s resolveIdentity() — requires the identity:resolve scope on the key). Prints the identity JSON plus the derived memory-scope partition keys, so an operator can verify exactly which app / agent / end-user identity the backend resolves before wiring those keys into a memory store.

Flag	Required	Description
--user-token <jwt>	no	End-user IDP JWT to resolve. Validated against the application’s configured identity provider.
--app-user-id <uuid>	no	Agent-only consent-edge shortcut: resolve this end user without a token. Requires a key bound to a managed agent that holds a delegation from that user — keys minted on the agent-keys surface currently use the legacy alter_key_… prefix; alter_ak_… keys are accepted too. The backend authorizes on the key’s agent binding, not its prefix; the CLI only rejects definitively non-agent prefixes (alter_rk_…, alter_dk_…, alter_pk_…) locally.
--include-profile	no	Opt into PII (email + display name) on the response. Off by default.
--api-key <key>	no	Runtime API key, if not using ALTER_API_KEY. Same rules as request above.

With neither --user-token nor --app-user-id, the call is headless and resolves the key’s own identity — the application, plus the agent identity when the key is bound to a managed agent.

There is deliberately no assert-identity counterpart: assertion-minting produces a signed credential-shaped token whose only consumers are programmatic verifiers, so it ships on the SDKs only.

# An agent-BOUND key (minted on the agent-keys surface).
export ALTER_API_KEY="alter_key_..."

# Which identity does this key resolve for this user's JWT?
alter sdk-passthrough resolve-identity --user-token "$USER_JWT" | jq .

# Consent-edge shortcut (agent key + a delegation from this user)
alter sdk-passthrough resolve-identity --app-user-id 22222222-2222-2222-2222-222222222222 | jq .memory_scope

Recipes

Debug a grant from scratch

# 1. Mint a runtime key (printed once) and export it.
alter keys mint --name debug --scopes tokens:retrieve --output json
export ALTER_API_KEY="alter_rk_..."
# 2. Call the provider through the grant and inspect the response.
alter sdk-passthrough request <grant-id> --url https://www.googleapis.com/oauth2/v3/userinfo | jq .

Related

• alter keys mint — create the runtime key this command uses
• Python SDK / TypeScript SDK — the supported way to make requests from application code