Authentication

The CLI authenticates product commands only with AK/SK-shaped credentials. Every request is signed; the platform decides per command whether the signing principal is allowed to perform it.

Which credential kind you want

Kind	Access-key id	Who it is for
Service user	AKIA…	scripts, CI and automation inside one Account
Workforce STS	ASIA… + session token	a human operator, time-bounded
Workload identity	— (token file)	a deployed runtime or CI job with an OIDC token

Service users

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

Service users do not get web-console access, and an Account owns them directly — they are not workforce users with a key attached. A service user that exists in the workforce directory only cannot sign a CLI request.

Temporary STS credentials

Temporary credentials use an ASIA… access-key id, a secret key, and a mandatory session token:

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"

Static and temporary credentials sign the same canonical request. STS requests additionally sign and send X-FGAI-Security-Token.

Human and platform-admin access

Human bearer tokens are not CLI credentials. Account root and workforce users use the tenant web applications. Platform administrators use the web admin console; there is no platform-admin profile or command family on the CLI.

Workload identity federation

Workload identities are for CI/CD and deployed runtimes. They exchange an external OIDC token for a short-lived platform access token:

fgai sts exchange-token \
  --profile prod \
  --subject-token-file ./github-oidc.jwt \
  --audience hello-api \
  --json

The token-exchange helper issues a workload JWT for the requested service audience, and prints it for the runtime to use on its OWN HTTP calls. It is not a stored CLI credential and it cannot drive a product command: those are authenticated only with an AWS-shaped access key: a static AKIA… or a temporary ASIA… STS credentials.

What the status codes mean

• 401 — the request was not authenticated. The credential is missing, malformed, expired, or signed for a different region. Start with fgai auth status.

• 403 — the request WAS authenticated and the action was refused for that principal. The credential is fine; the grant is not. Narrow principals are refused account-wide reads by design.

Authorization is decided by the platform on every call, not by the CLI, so a 403 is an answer rather than a client error.