Machine identities

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

Create and grant

hikyo sa create --name payments-deploy --kind workload
hikyo access grant add \
  --principal <service-account-id> \
  --capability <read-capability>

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-in

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 credential

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 policy

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 federation

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: repository and event_name.

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.

Delete

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.