Run the CLI in CI with machine credentials

In CI the HexSign CLI runs in machine mode. It uses the OAuth2 client_credentials grant, fetches a short-lived access token on each invocation, and never touches the OS keychain. You provision the credential once in the dashboard and store the secret in your pipeline's encrypted-secrets store.

Provision a service credential

1. 1

   Open Settings → CLI Tokens in the dashboard

   Only Owners can create service credentials. Click "New CLI token", give it a descriptive name (e.g. "GitHub Actions — release"), and pick the scopes the pipeline needs.

2. 2

   Copy the client ID and secret

   The dashboard shows the `client_secret` exactly once. Copy it immediately into your CI's secrets store — you can't read it again later.

3. 3

   Store both in your pipeline

   Add `HEXSIGN_CLIENT_ID` and `HEXSIGN_CLIENT_SECRET` as encrypted secrets (GitHub Actions secrets, GitLab CI variables, Bitrise secret env vars). Never commit them to your repo.

Set the env vars in CI

When both `HEXSIGN_CLIENT_ID` and `HEXSIGN_CLIENT_SECRET` are present in the environment, the CLI automatically switches to machine mode. There's no flag to toggle.

# .github/workflows/release.yml
- name: Sync expiring items
  env:
    HEXSIGN_CLIENT_ID:     ${{ secrets.HEXSIGN_CLIENT_ID }}
    HEXSIGN_CLIENT_SECRET: ${{ secrets.HEXSIGN_CLIENT_SECRET }}
  run: hexsign certificates expiring -o json

How scopes work

hexsign-api/read

Required by every `GET` request — listing certificates and profiles, fetching summary, downloading existing material.

hexsign-api/write

Required for any mutation: create, update, regenerate, revoke, delete. Pipelines that only fetch artifacts don't need this.

Blocked routes

Service credentials can never call `/users`, `/subscriptions`, `/contact-form`, or `/service-credentials` — the API blocks those for machine tokens because they manage humans and billing.

Optional: explicit scopes

By default the CLI requests both `hexsign-api/read` and `hexsign-api/write` if the credential allows them. To restrict a single run to read-only — handy for jobs that should only fetch — set `HEXSIGN_CLIENT_SCOPES`.

export HEXSIGN_CLIENT_SCOPES="hexsign-api/read"
hexsign certificates list -o json

Audit and revoke

Every successful machine-mode request updates the credential's `last_used_at` in the dashboard so you can spot stale or compromised tokens. Revocation is immediate from Settings → CLI Tokens → Revoke.