CLI authentication for DotID¶

The FGAI CLI calls tenant-external capability APIs through the public API edge. It does not call /cli/*, browser APIs, platform-admin APIs, or Keycloak Admin APIs.

Supported credentials¶

The CLI accepts two credential shapes. Which shape a principal uses is not fixed by what kind of principal it is:

Shape	Credential	Use
Static	`AKIA…` access-key id and secret	Long-running tenant automation; no console access
Temporary	`ASIA…` access-key id, secret, and session token from DotID STS	Any principal, for a bounded session: a workforce user through `auth workforce login`, any other principal through `identity sts assume-role`

A temporary credential is not a workforce privilege. POST /api/v1/sts/assume-role mints ASIA credentials for a caller it resolves as either a JWT or an AK/SK, and gates the request on the target role’s trust policy, fail-closed — not on the caller’s realm. So a service user or a machine persona can hold a short-lived, revocable credential instead of a long-lived key, and that is the preferred shape wherever a trust policy can express the caller. (POST /api/v1/sts/get-session-token is the separate workforce convenience path and does require an idc-* realm, because it issues against a permission-set assignment.)

CLI API calls use FGAI-HMAC-SHA256 in both cases. An STS request must include X-FGAI-Security-Token in the signed headers. Human OAuth/OIDC bearer tokens are not CLI credentials. This includes Account root, workforce, Identity Center, and platform-admin bearer tokens.

Every protected public API-edge operation is required to support both shapes — a static AKIA… and a temporary ASIA… with its session token. Authorization is still evaluated per action, resource, permission set, Organization authority, and tenant boundary; authentication support does not grant equal permissions.

Configure a service-user key¶

fgai configure \
  --profile prod \
  --account-id "$ACCOUNT_ID" \
  --access-key-id "$ACCESS_KEY_ID" \
  --secret-access-key "$SECRET_ACCESS_KEY" \
  --name automation

Service users are Account-owned API principals. They have no password, MFA method, Profile, or web-console session.

Configure a workforce STS session¶

fgai configure \
  --profile prod \
  --account-id "$ACCOUNT_ID" \
  --access-key-id "$STS_ACCESS_KEY_ID" \
  --secret-access-key "$STS_SECRET_ACCESS_KEY" \
  --session-token "$STS_SESSION_TOKEN" \
  --name workforce-session

Temporary access-key ids use the ASIA… prefix. The CLI rejects ASIA credentials without a session token and rejects a session token paired with a static AKIA key. Workforce STS acquisition/refresh must not persist a human bearer token as a CLI profile. The end-to-end acquisition UX and route-by-route parity migration are owned by platform GSD Phase 49.

Workload federation is separate¶

fgai sts exchange-token is a helper for an external workload OIDC subject to obtain a service-audience JWT from POST /oauth2/token. That JWT is for CI/runtime service calls; it is not stored or used as a CLI command credential.

Audience rules¶

Platform administrators use the web admin console and its private same-origin APIs. There is no platform-admin CLI profile or command family.
Creating the first root user and a new standalone Account is browser onboarding. Bare POST /accounts/v1 is not a public/CLI operation.
An authorized management Account may provision member Accounts inside an existing Organization through public APIs and the CLI, including batch provisioning.
Tenant quota reads/requests, own-account audit reads, service registration intake, and tenant identity/Organization operations are public only when their owner supports both AK/SK and STS.
Platform quota definitions/decisions, cross-account audit, platform directories, and registration approvals/refusals/revocations are admin-console-only.

Local credential storage¶

Credential files use the OS-native config directory with owner-only permissions. Set FGAI_CLI_HOME for isolated tests. fgai auth status --json shows metadata without printing secrets or session tokens; fgai auth logout --name NAME removes the local profile but does not revoke the server-side key/session.