Deployments.ai Docs

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:

  • identity makes sure a human platform administrator can sign in with a password that lives in a Parameter Store SecureString parameter.
  • token signs in as that identity and mints a short-lived platform bearer token.
  • api-key makes 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

CommandAWSPlatform
identityDynamoDB 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.
tokenWith --password-secret: ssm:GetParameter on the parameter.The identity must exist and be able to sign in.
api-keyssm: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:

StateWhat it writesoutcome
No principal, or a principal without login materialOne 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 eventscreated
Login material whose active password hash verifies the passwordNothingunchanged
Login material that does not verify the password, or --rotateA 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-credential and Purpose=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> --rotate

api-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.

  1. 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".
  2. It reads --secret. If the parameter holds an active key of another service account, it fails without changing anything.
  3. If the parameter holds this service account's active key named --name with exactly --scopes, it checks that the key authenticates with one GET. A key that passes stays, and the outcome is unchanged. A stored key with other scopes fails with "refusing to change them".
  4. 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 is rotated when a key was replaced and created otherwise.

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

CommandWithout --rotateWith --rotate
identityKeeps the login while the parameter's password verifiesNew password in the parameter, then a new credential version and session epoch
api-keyKeeps the stored key while it is current, matching, and workingNew 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.

Reference

On this page