Operator credentials
Keep a password-login operator identity and durable environment API keys in AWS Systems Manager Parameter Store with one idempotent tool, and mint short-lived platform tokens from them.
The credential tool, bun run credential, gives operators and automation durable platform credentials without a person in the loop. It has three commands:
identitymakes sure a human platform administrator can sign in with a password that lives in a Parameter Store SecureString parameter.tokensigns in as that identity and mints a short-lived platform bearer token.api-keymakes sure an environment has a named service account and API key, and keeps the key in a SecureString parameter.
Every command converges: run it again with the same flags and it changes nothing that is already correct. Flags carry only identifiers. Passwords and API keys never appear in flags, in output, or in error messages. The only secret the tool prints is the bearer token that token mints.
Where it runs
The tool is a script in the platform repository, not part of the deployments CLI. Run it from a
checkout after bun install. AWS credentials and the region come from the standard AWS SDK chain.
Required access
| Command | AWS | Platform |
|---|---|---|
identity | DynamoDB read and transactional write on the installation's control, identity, and events tables. With --password-secret: ssm:GetParameter and ssm:PutParameter on the parameter, and ssm:AddTagsToResource on create. | None. It writes the identity records directly, so run it with the installation's own AWS credentials. |
token | With --password-secret: ssm:GetParameter on the parameter. | The identity must exist and be able to sign in. |
api-key | ssm:GetParameter and ssm:PutParameter on --secret, and ssm:AddTagsToResource on create. Add the token permissions when the tool mints its bearer. | A bearer that may manage service accounts and API keys in the environment and holds every scope in --scopes, because a caller grants only scopes it holds. |
identity reads table names from DEPLOYMENTS_AI_CONTROL_TABLE, DEPLOYMENTS_AI_IDENTITY_TABLE, and DEPLOYMENTS_AI_EVENTS_TABLE. Each defaults to the bare table name.
Ensure an operator identity
bun run credential -- identity \
--principal-id <principal-id> \
--username ops@example.com \
--password-secret <password-parameter>--principal-id is the ULID the principal has or gets. identity checks the stored state, then does exactly one of these:
| State | What it writes | outcome |
|---|---|---|
| No principal, or a principal without login material | One transaction with the platform administrator principal, its password credential, security state, session fence, the email uniqueness claim, and the identity.operator-login-enabled and identity.credentials-created events | created |
| Login material whose active password hash verifies the password | Nothing | unchanged |
Login material that does not verify the password, or --rotate | A new credential version, the next session epoch on the security state and fence, and an identity.credentials-rotated event. Every existing session ends. | rotated |
It refuses to act when the principal is not an active human, is not a platform administrator, has a different ID, has only part of its login material, or has a session fence that disagrees with its security state. It never promotes an existing principal to platform administrator; use bun run deploy -- admin bootstrap for that.
Where the password comes from
With --password-secret, the parameter is the source of truth:
- If the parameter does not exist, the tool generates a random 256-bit password, creates the parameter as a SecureString with it, and tags it
ManagedBy=deployments-platform-credentialandPurpose=operator-password. - If the parameter exists, the tool uses its current value.
- With
--rotate, the tool first writes a new generated password to the parameter, then rotates the login to it.
--password-secret and --secret take a parameter path such as /operators/ops/password. The parameter always changes before the identity. If the identity write fails, the next run reads the new password, finds that it does not verify, and finishes the rotation.
Without --password-secret, the tool reads the password from DEPLOYMENTS_OPERATOR_PASSWORD, and --rotate is not allowed. To rotate that password, change the variable and run identity again.
The command prints one JSON line, for example {"outcome":"unchanged","principalId":"<principal-id>","secretArn":"<parameter ARN>"}. secretArn appears only with --password-secret.
Mint a platform token
bun run credential -- token \
--api-url https://api.example.com \
--issuer https://auth.example.com \
--username ops@example.com \
--password-secret <password-parameter>token starts a device authorization for the deployments-cli client at the API origin, signs in at the identity origin, claims and approves the user code, and exchanges the device code for a bearer token. It sends the password only to the --issuer origin. The verification URI the API returns is the console's /device page, which token checks for an https /device URL and never opens. The password comes from --password-secret or DEPLOYMENTS_OPERATOR_PASSWORD; token never creates or changes the secret.
It prints only the token. --format json prints {"expiresAt":"…","token":"…"} instead. The token is short-lived, so mint one per job. In GitHub Actions, mask it before you use it:
token="$(bun run credential -- token --api-url https://api.example.com --issuer https://auth.example.com --username ops@example.com --password-secret <password-parameter>)"
echo "::add-mask::${token}"Ensure an environment API key
bun run credential -- api-key \
--api-url https://api.example.com \
--org <organization-id> --project <project-id> --env <environment-id> \
--name agent-reconciler \
--scopes agents:read,agents:write \
--secret <api-key-parameter> \
--issuer https://auth.example.com \
--username ops@example.com \
--password-secret <password-parameter>The tool authenticates with DEPLOYMENTS_API_KEY when it is set. Otherwise it mints a bearer the way token does, from --issuer, --username, and the password. Give one bearer source; the tool rejects DEPLOYMENTS_API_KEY together with the sign-in flags.
A token minted from an identity carries the scopes the CLI client grants, which do not include every scope (channels:read and channels:write, for example). To issue a key with such a scope, use DEPLOYMENTS_API_KEY with a key that holds it. When --scopes includes service-accounts:read, api-keys:read, and api-keys:write, the stored key can rotate itself:
DEPLOYMENTS_API_KEY="$(aws ssm get-parameter --name <api-key-parameter> --with-decryption \
--query Parameter.Value --output text)" \
bun run credential -- api-key <same flags as before> --rotateapi-key follows the OpenTofu provider's rules. It sends the tenancy headers on every request and a new idempotency-key on every write, and it pages through every list.
- It finds the active service account named
--name, or creates it with--scopes. An existing account with other scopes fails with "refusing to change them". - It reads
--secret. If the parameter holds an active key of another service account, it fails without changing anything. - If the parameter holds this service account's active key named
--namewith exactly--scopes, it checks that the key authenticates with oneGET. A key that passes stays, and the outcome isunchanged. A stored key with other scopes fails with "refusing to change them". - Otherwise, or with
--rotate, it issues a new key and checks it. It then writes the key to the parameter, creating it as a SecureString when it does not exist, and only then revokes the key it replaced. The outcome isrotatedwhen a key was replaced andcreatedotherwise.
The check uses the first of these scopes that --scopes contains, the same table the provider uses. The tool rejects --scopes without one of them before it calls AWS or the platform: approvals:read, agents:read, channels:read, workspaces:read, tools:read, schedules:read, or webhooks:read.
If a new key fails its check or cannot be written to the parameter, the tool revokes the new key and leaves the parameter and the old key as they were. Consumers of the parameter always read a working key.
The parameter value is the plain API key string, the same format the OpenTofu provider writes. A parameter the tool creates is tagged ManagedBy=deployments-platform-credential and Purpose=environment-api-key. The command prints one JSON line with serviceAccountId, apiCredentialId, keyPrefix, secretArn (the parameter ARN), secretVersionId (the parameter version), and outcome.
Durability and rotation
| Command | Without --rotate | With --rotate |
|---|---|---|
identity | Keeps the login while the parameter's password verifies | New password in the parameter, then a new credential version and session epoch |
api-key | Keeps the stored key while it is current, matching, and working | New key in the parameter, then the old key is revoked |
Scheduled jobs should run without --rotate, so a run that finds everything correct writes nothing and ends no sessions. Rotate on a schedule you choose, or after a suspected leak.