Configure

fgai configure stores a signed-credential profile on this machine, similar in spirit to aws configure. Use static AKIA… credentials for an Account service user, or temporary ASIA… credentials for an STS session. Any principal may hold the temporary shape — it is obtained with fgai identity sts assume-role, which gates on the target role’s trust policy.

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

The default credential name is default; --name lets you keep several on one machine and pick between them with --auth:

fgai org directory --auth ci-service-user --json

Check what is stored at any time:

fgai auth status

For a temporary STS credential, also pass --session-token "$STS_SESSION_TOKEN". Human bearer tokens are not CLI credentials; do not paste browser tokens into fgai configure.

A renewable human session

For a human operator, use the device-authorization command instead of copying STS material by hand:

fgai auth workforce login \
  --profile prod \
  --email "$WORKFORCE_EMAIL" \
  --account-id "$ACCOUNT_ID" \
  --permission-set-id "$PERMISSION_SET_ID"

After the one-time approval, fgai auth workforce renew and ordinary commands rotate the bounded renewal capability without reopening a browser. The access token is never persisted or used to authenticate product commands. Human workforce renewal is rejected in CI; use a workload identity there.

Explicit forms

fgai configure is shorthand. Each credential kind also has an explicit form:

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

There is no third form. CLI commands are authenticated only with AWS-shaped signed credentials, so a workload (RFC 8693) bearer is not a credential kind fgai configure accepts. fgai sts exchange-token still mints one for a workload’s own HTTP calls — it is a runtime helper, not a stored profile.

Recording when a pasted session expires

A session token dies at a fixed moment. fgai auth workforce login learns that moment from the exchange; a session you PASTE in has to be told:

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" \
  --expiration 2026-08-19T12:00:00Z

--expiration takes an RFC 3339 instant, and only alongside --session-token (a static AKIA… credential does not expire). With it, fgai auth status reports the remaining lifetime and the CLI refuses a command outright once the session is dead instead of letting the service answer 401. Without it, status reports expires: unknown (pasted session) — the CLI will not stay silent about a credential it knows can die.

Where credentials are written

Credential files are written under the OS-native user config directory. Set FGAI_CLI_HOME to send the whole store somewhere disposable — useful for tests and for anything that must not touch your real credentials:

FGAI_CLI_HOME="$(mktemp -d)" fgai configure \
  --profile prod \
  --account-id 11111111-1111-1111-1111-111111111111 \
  --access-key-id AKIA_TEST \
  --secret-access-key test-secret

Removing a credential

fgai auth logout --name ci-service-user

The auth commands select a credential with --name, not the --auth flag the product commands use. --auth on fgai auth logout is ignored, and the command then reports on default instead — check the name it echoes back.

For a workforce session, logout ends the live session at the platform before the local material is deleted, so deleting the files by hand is not the same thing. If the remote revocation fails, the local credential is deliberately KEPT so the logout can be retried.