API Key Management

This page describes the CLI workflow for storing, using, and rotating API keys: storing them securely, using them for signing, and rotating them on a schedule. For a conceptual overview of the full key lifecycle, see API Key Lifecycle.

Workflow Overview

  1. Store an API key obtained from the Web UI using auth set-key
  2. Sign artifacts by referencing the stored key with the sign command
  3. Rotate keys periodically using rotate-key for zero-downtime updates

Securing API Keys

Use the auth set-key command to write an API key to a secure file without exposing it in shell history or version control.

Example -- read from stdin and write to a key file:

echo your-api-key-here | SignotaurTool auth set-key --from-stdin --write-key-file %USERPROFILE%\.signotaur\api_key.txt

The command also supports reading from environment variables (--from-env), writing dotenv files (--write-env-file), server-side verification (--verify), and idempotent writes (--if-missing). See auth set-key Command for the full option reference.

Using API Keys for Signing

SignotaurTool resolves API keys from several sources in priority order (command-line argument, key file, environment variable, config file). See the sign Command -- Authentication section for the complete priority list.

Example -- sign using a key file:

SignotaurTool sign --api-key-file %USERPROFILE%\.signotaur\api_key.txt -s https://signotaur.example.com --label production --fd SHA256 myapp.exe

Use --fail-if-expiring-within (e.g. 7d) in CI/CD builds to catch keys that are about to expire before they cause failures. See sign Command for all signing options and key file format details.

Rotating API Keys

The rotate-key command creates a new API key while keeping the old key valid during a configurable overlap period (default 7 days, max 30). After the overlap expires the server automatically revokes the old key, giving you time to propagate the new key to all systems with no downtime.

Example -- rotate and overwrite the existing key file:

SignotaurTool rotate-key --api-key-file %USERPROFILE%\.signotaur\api_key.txt -s https://signotaur.example.com --write-key-file %USERPROFILE%\.signotaur\api_key.txt

See rotate-key Command for all options including custom overlap periods, dotenv output, --emit-secret for CI/CD platforms, and --no-auto-revoke.

For patterns on integrating rotation into scheduled pipelines, see CI/CD Integration Best Practices.

See Also

  • CI/CD Integration Best Practices -- Two-pipeline patterns for signing and rotation
  • API Key Lifecycle -- Conceptual overview, security best practices, and policy recommendations
  • auth set-key Command -- Full command reference for storing API keys
  • sign Command -- Full command reference for signing operations
  • rotate-key Command -- Full command reference for key rotation
  • Server Admin - Users -- Managing API keys via Web UI (admin)
  • User Profile - API Keys -- Managing your own API keys via Web UI