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.