Skip to content

Access commands

Common global behavior is documented in the CLI hub. The complete access, MFA, and step-up command contracts follow.

gdsgate ls

Lists resources the policy lets you view (RBAC-filtered). Output is a table on stdout:

RESOURCE                 NAME                 KIND         PORT   ENV        LABELS
prod-db                  prod-db              postgres     5432   prod       team=backend
web-01                   web-01               ssh          22     dev        team=frontend
edge.svc                 -                    tcp          -      prod

NAME is the name the resource may be addressed by, plus any aliases; PORT is what a connection goes to: declared in the catalog, else the well-known port of the kind. A dash means the catalog publishes neither: an id carrying _ or . is not a legal name, and tcp / mcp / llm / web / web-egress have no well-known port to fall back on. A web resource's native_name does not appear here, since this is the policy-filtered catalog rather than a resident client's own board; see gdsgate status above and Resident client → An application's own name.

gdsgate request-access <resource> --reason <text> [--action <action>] [--ttl <secs>]

Files a JIT access request for <resource> (logged to the audit chain). Prints the request id.

Flag Default Purpose
--reason <text> required Justification shown to approvers. Required.
--action <action> connect Cedar action the elevation is scoped to. connect covers opening a session on any kind of resource; name something inside a session (kubeRequest, mcpCallTool) to elevate there instead.
--ttl <secs> 3600 Requested elevation window.

gdsgate approve <id>

Confirm a pending access request as one approver. The required number of distinct approvers comes from the approvals cascade.

gdsgate requests

Lists pending and recent access requests with their approval state.

gdsgate mfa enroll

Starts TOTP enrollment. Prints an otpauth:// URI (scan as a QR code) and the base32 secret for manual entry; add it to an authenticator app, then activate it with gdsgate mfa confirm <code>. The factor does not satisfy any policy until confirmed.

gdsgate mfa confirm <code>

Activates a pending TOTP enrollment with the first code from your app.

gdsgate mfa verify <code>

Performs a gateway TOTP step-up: refreshes your step_up_satisfied / totp_satisfied recency so a policy that demands a fresh step-up (Policy → Two MFA channels) admits the next request. Run it when a call is denied because it needs a fresh gateway step-up. (It refreshes the gateway step_up_* channel, not the IdP-login mfa_satisfied channel.)

gdsgate mfa register-passkey

Registers a WebAuthn passkey. With [proxy].public_origin set it opens the gateway's own registration page (https://<public_origin>/mfa/register/…) and polls until you create the passkey there, so the credential is scoped to the gateway domain; without it, the dev localhost loopback is used. The gateway must have a relying party configured ([mfa.webauthn]). One-off: afterwards step up with gdsgate step-up <resource>.

gdsgate mfa step-up

Performs a WebAuthn step-up (passkey assertion) in the browser, refreshing your webauthn_satisfied / step_up_satisfied recency. The reusable counterpart of gdsgate step-up <resource> (which mints a single-use grant).

gdsgate step-up <resource> [--action <action>] [--code <totp>]

Mints a one-time step-up grant bound to (you, resource, action), spent by the next request the policy lets through because of it; a request some other rule would have allowed anyway leaves it alone. Without --code it opens the gateway's own confirmation page (https://<public_origin>/mfa/confirm/…) and polls until you complete the passkey there, so the credential is scoped to the gateway domain (requires [proxy].public_origin); with --code <totp> it uses TOTP. Use it when a deny needs a one-time grant for this resource, and the refusal names the whole command, --action included.

<resource> is a resource id for connect and for llmCall, and an MCP tool-id (<server>.<tool>) for mcpCallTool. For the six discrete acts it is the id of the thing being acted on: a session uid (viewRecordings or killSession), the role a token becomes (issueJoinToken), a certificate-authority slug (rotateCA), an access-request id (approveRequest) or a policy-proposal version (approvePolicyEdit). A Kubernetes cluster can also take --action kubeRequest; that per-request grant is keyed to the cluster and the policy must narrow it with the request context it intends to authorise.

Flag Default Purpose
--action <action> derived from the resource's catalogued kind (ssh / database / TCP → connect, mcp → mcpCallTool, llm → llmCall) Cedar action the grant applies to: connect, kubeRequest, httpRequest, mcpCallTool, mcpReadResource, mcpGetPrompt, llmCall, viewRecordings, issueJoinToken, killSession, rotateCA, approveRequest, approvePolicyEdit. Required when the resource is not a catalogue entry. kubeRequest spends one grant per apiserver request; pair its marker with the verb, kind, namespace/name and any subresource the rule means to authorise.
--code <totp> none Mint a TOTP-backed grant instead of a passkey ceremony.

enroll confirm verify register-passkey step-up