Secrets in CI

A machine identity gives a pipeline, a server or a script read access to one environment. It signs in with a token, or with its platform's OIDC token in a Managed project.

Create a machine identity

sphragis identities create deploy-bot --project payments-api --env prod

The CLI prints the identity's token once. Store it as a secret in your CI system. The identity gets the secret_reader role unless you pass --role with viewer, secret_writer or admin.

Read secrets with a token

Set SPHRAGIS_TOKEN in the job. The CLI then reads with that token and needs no sign-in.

export SPHRAGIS_TOKEN="$DEPLOY_BOT_TOKEN"
sphragis run --project payments-api --env prod -- ./deploy.sh

Rotate a token

sphragis identities rotate ID TOKEN_ID --overlap-hours 24

The CLI prints a new token once. The old token keeps working for the overlap you choose, from 0 to 720 hours. Zero revokes it at once. sphragis identities token ID --days 30 issues another token that expires after 30 days.

Sign in with OIDC, without a stored token

In a Managed project, a workload can prove who it is with a token from its own platform. Sphragis trades that token for a short-lived access token. Nothing long-lived is stored in the pipeline.

1. Create the project with sphragis projects create SLUG --managed.
2. Create a machine identity for it and add a trust policy for your platform in the web vault, under Secrets and then Machine identities.
3. In the job, set SPHRAGIS_IDENTITY_ID to the identity's id and run the CLI. Leave SPHRAGIS_TOKEN unset.

The CLI finds the platform token in this order:

The token's audience is sphragis unless you set SPHRAGIS_OIDC_AUDIENCE.

OIDC works with Managed projects only. A Zero-knowledge project's key never leaves your vault and the machine identities you grant, so a platform token alone cannot open it.