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.

Install the CLI

The fgai CLI is published on dl.flexgalaxy.ai for macOS and Linux:

curl -fsSL https://dl.flexgalaxy.ai/fgai/install.sh | PREFIX="$HOME/.local" bash

fgai version

The installer verifies the release’s SHA-256 checksum before installing and — when the GitHub CLI is present and authenticated — also verifies the signed build provenance (set FGAI_REQUIRE_ATTESTATION=1 to make provenance a hard requirement). Then configure a credential (below).

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: it issues against a permission-set assignment, so it requires a workforce session bound to one — a session issued from the platform realm.)

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 auth service-user configure \
  --profile prod \
  --account-id "$ACCOUNT_ID" \
  --access-key-id "$ACCESS_KEY_ID" \
  --secret-access-key "$SECRET_ACCESS_KEY" \
  --name automation

(fgai configure remains a short alias for this verb.) The --name you choose here is the credential name every later command selects with --auth <name> — for example fgai account get --account "$ACCOUNT_ID" --auth automation.

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

Configure a workforce STS session

Use the dedicated verb — it runs the device-code login and stores the session for you:

fgai auth workforce login --email you@example.com --account-id "$ACCOUNT_ID" \
  --permission-set-id "$PERMISSION_SET_ID"

Workforce login needs an account that has an Identity Center directory: the --account-id you pass must be an Identity Center instance, and --email a workforce user in it. On an account without one the command refuses with unknown_instance; for any root or service-user identity, use fgai auth service-user configure with the identity’s access keys instead of a device login.

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-operator operations are reachable from the fgai-admin CLI as well as the web admin console and its private same-origin APIs. There IS a platform-operator command family; it lives in the operator binary and is not part of the tenant fgai binary (PLT-0092).

  • 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 platform-operator surfaces: reachable from the fgai-admin CLI and the admin console, never from a tenant surface.

  • The only browser-only operations are creating a standalone Account and its first root user (PLT-0092).

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.