Access commands¶
Common global behavior is documented in the CLI hub. The complete access, MFA, and step-up command contracts follow.
gdsgate resources list [--leased]¶
Lists resources the policy lets you view (RBAC-filtered). Output is a
table on stdout:
resource name kind port env lease
edge.svc - tcp - prod -
prod-db prod-db postgres 5432 prod -
test-orders-db test-orders-db postgres 5432 test 14m
web-01 web-01 ssh 22 dev -
| Column | Value |
|---|---|
name |
Name the resource is addressed by, plus aliases. A dash when the id carries _ or . (not a legal name). |
port |
Port a connection goes to: declared in the catalog, else the kind's well-known port. A dash for tcp, mcp, llm, web, web-egress without a declared port. |
lease |
Time left before a resource written inside an auto-scope expires unless renewed. expired: the lease ran out and the row is not swept yet. A dash: declared by an operator, no lease. |
--leased lists only rows that hold a lease. --wide adds serving,
onward auth, native name and labels. --json prints one object per
resource; a field the table shows as a dash is absent.
db list, kube list, rdp list, tcp list and mcp list print the same table with
the same flags, filtered to their kinds.
gdsgate requests create <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 an action inside a session (kubeRequest, mcpCallTool) to elevate that action. |
--ttl <secs> |
3600 |
Requested elevation window. |
gdsgate requests approve <id>¶
Confirm a pending access request as one approver. The required number of distinct approvers comes from the approvals cascade.
gdsgate requests list¶
Lists pending and recent access requests with their approval state.
Columns: id, requester, resource, action, state, approvals,
reason. --wide adds expires, the end of the elevation window of an
approved request; a dash while the request is pending. --json prints one
object per request.
gdsgate mfa totp 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 and activate it
with gdsgate mfa totp confirm <code>. An unconfirmed factor satisfies no policy.
gdsgate mfa totp confirm <code>¶
Activates a pending TOTP enrollment with the first code from your app.
gdsgate mfa totp 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 for lack of a fresh gateway step-up. It
does not refresh the IdP-login mfa_satisfied channel.
gdsgate mfa passkeys register¶
Registers a WebAuthn passkey. With [proxy].public_origin
set, it opens the gateway's registration page (https://<public_origin>/mfa/register/...)
and polls until you create the passkey there; the credential is scoped to the
gateway domain. Without it, the dev localhost loopback is used. Requires a
relying party in [mfa.webauthn]. Run once; then
step up with gdsgate mfa grants create <resource>.
gdsgate mfa passkeys verify¶
Performs a WebAuthn step-up (passkey assertion) in the browser and refreshes
your webauthn_satisfied / step_up_satisfied recency. Reusable;
gdsgate mfa grants create <resource> issues a single-use grant.
gdsgate mfa grants create <resource> [--action <action>] [--code <totp>]¶
Issues a one-time step-up grant bound to (you, resource, action). The grant is
spent by the next request the policy admits on it; a request another
rule allows leaves it unspent. Without --code it opens the gateway's
confirmation page (https://<public_origin>/mfa/confirm/..., requires
[proxy].public_origin) and polls until you
complete the passkey there. With --code <totp> it uses TOTP. A deny that
needs a grant names the full 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 also
takes --action kubeRequest: the grant is keyed to the cluster, and the policy
must narrow it by request context.
| Flag | Default | Purpose |
|---|---|---|
--action <action> |
derived from the resource's catalogued kind (ssh / database / TCP / web / desktop → 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; the rule pairs its marker with verb, kind, namespace/name and subresource. |
--code <totp> |
none | Issues a TOTP-backed grant. Without it, the command opens a passkey ceremony. |
enroll confirm verify register-passkey step-up