Guidal
Sign in

API keys

Authenticate scripts, CI pipelines and agents without an interactive login.

API keys authenticate automated callers. Anything that cannot open a browser — a CI pipeline, a deploy script, an unattended agent — uses a key instead of guidal login.

Create a key

bash
guidal api-keys create ci-deploy

The key is displayed once, at creation. Store it immediately in your CI provider's secret store or a password manager.

The value is shown once and never again

There is no command that prints an existing key's value. If you lose it, delete the key and create a new one. This is deliberate — a key you can read back is a key an attacker can read back.

List and inspect

bash
guidal api-keys list
guidal api-keys get ci-deploy

These show metadata — name, creation time, last use — never the secret. Give keys names that identify where they run (ci-deploy, backup-job) so an unexpected entry is obviously wrong.

Use a key

Export it and the CLI will use it instead of an interactive session:

bash
export GUIDAL_ACCESS_TOKEN="<your-api-key>"
guidal services deploy api --image ghcr.io/your-org/app:"$GIT_SHA"

In GitHub Actions:

yaml
- name: Deploy
  env:
    GUIDAL_ACCESS_TOKEN: ${{ secrets.GUIDAL_ACCESS_TOKEN }}
  run: |
    pip install guidal
    guidal services deploy api \
      --image ghcr.io/your-org/app:${{ github.sha }} \
      --project my-app

Note the explicit --project: a CI runner has no stored context, so commands should name the project rather than relying on a previous projects switch.

Revoke a key

bash
guidal api-keys delete ci-deploy

Revocation takes effect immediately. Any pipeline using that key starts failing authentication on its next run, so replace the secret before revoking if the pipeline needs to keep working.

Practices worth following

One key per consumer. Separate keys for CI, for a backup script, and for an agent mean you can revoke one without breaking the others, and last-use timestamps tell you which is which.

Rotate on a schedule, and on departure. Create the replacement, update the consumer, confirm it works, then delete the old key — in that order, so there is no window where the pipeline has no valid credential.

Never commit a key. Not in source, not in a Dockerfile, not in a compose file. Keys belong in a secret store. A key committed to a repository should be treated as compromised and revoked, even in a private repository.

Prefer a key over a personal login in automation. A pipeline authenticating as a person breaks when that person leaves, and attributes every action to them.