Machine identities

Use a service account for a workload or automation job. Give it only the capabilities and scope required by that workload.

Automation can create and delete ordinary environments, stage and publish its own changes, and copy values under the existing disclosure gates. Environment lifecycle requires project-wide definitions-edit; protected environments cannot be deleted by machines. The preview guide shows a dedicated-project recipe with cloning, explicit publication, export and cleanup.

Create and grantCopy Anchor Link

hikyo sa create --name payments-deploy --kind workload
hikyo access grant add \
  --principal <mch_...> \
  --capability read \
  --env <environment-id>

Record the returned stable ID. List its grants before minting a credential.

In the browser, Machine access offers the same acts: Create service account, Add environment grant, Mint credential, Revoke, and Delete (Operate Hikyo from the browser).

--principal takes the service account’s principal ID (mch_..., the principal_id field of hikyo sa list -o json), not its sa_... row ID.

Secret delivery: the machine-reveal opt-inCopy Anchor Link

A workload or automation principal may hold reveal only under the project’s explicit machine-reveal opt-in. A workload may also hold reveal-history, but only while an active pin routes that workload to a non-current revision. The opt-in is off by default; while it is off every machine fetch delivers configuration and secret presence only.

hikyo project-settings machine-reveal get
hikyo project-settings machine-reveal set --enabled true
hikyo access grant add --principal <mch_...> --capability reveal --env <env-id>

After pinning a workload to a non-current revision, grant its historical delivery atom separately:

hikyo access grant add --principal <mch_...> --capability reveal-history --env <env-id>

The grant is refused without a live non-current pin. Releasing the pin leaves the row visible for audit and reversal, but makes it inert and moves the workload cursor. Automation principals cannot hold this atom because pins name workloads.

Enabling needs project-settings and reveal at project scope and a second factor; it admits a standing decryption capability onto machine principals, which the command says before it writes. Withdrawing it (--enabled false) makes every machine reveal and workload reveal-history grant in the project inert on the next fetch and moves every machine cursor; grant rows are untouched.

Bearer credentialCopy Anchor Link

Mint to a new protected file:

hikyo sa credential mint \
  --sa <service-account-id> \
  --lifetime 720h \
  --output-file ./hikyo-token

The credential is shown once. A workload supplies it with --token-file or HIKYO_TOKEN; Hikyo has no --token flag.

Prefer --token-file. Environment variables remain visible to the process and may be copied by diagnostic tooling.

Rotate before expiry, distribute the new credential, verify it, then revoke the old credential. A rotate command does not make distribution atomic.

Credential policyCopy Anchor Link

The instance policy limits lifetime, indefinite credentials, and the number of live credentials per service account.

hikyo instance-config credential-policy get
hikyo sa credential list --sa <service-account-id>

Change policy only after checking existing workloads. Tightening a limit may require staged rotation.

OIDC federationCopy Anchor Link

Federation removes stored bearer credentials. Configure a trusted issuer, then create an immutable binding from exact claims to one service account.

Bindings do not accept wildcards or prefixes. Every platform binding must pin its immutable identifiers:

• GitHub Actions: repository_id, repository_owner_id, and event_name.
• Kubernetes: /kubernetes.io/serviceaccount/uid.

Forgejo Actions bindings are refused because its tokens do not expose an immutable repository identifier. Pinning repository and event_name cannot prevent a renamed or reused repository path from inheriting authority. Use a scoped bearer credential for Forgejo jobs instead.

Create a replacement binding for a change; do not edit the old binding in place:

hikyo sa binding create \
  --sa <service-account-id> \
  --issuer <issuer-url> \
  --subject <subject> \
  --audience <audience> \
  --claim name=value \
  --replaces <old-credential-id>

The server revokes the predecessor and inserts the successor in one transaction. There is no overlap window in which to verify both. Validate the new formula before invoking replacement, then test the successor immediately afterward.

Each federation token presentation is verified before the caller is known, so it counts against the per-source-IP allowance of 10 attempts per sliding minute. CI jobs sharing one egress address share that allowance; see Rate limits for how to spread calls and reuse one export per job.

DeleteCopy Anchor Link

hikyo sa credential revoke --sa <service-account-id> --id <credential-id>
hikyo sa delete --id <service-account-id>

Deletion is not a substitute for incident rotation. Revoke exposed credentials immediately, then investigate their audit history.

Next: review identity and access.