Rotate Key command

The rotate-key command enables seamless API key rotation with overlapping validity periods. This allows you to update API keys in CI/CD systems without downtime - both the old and new keys remain valid during a configurable overlap period, after which the old key can be automatically revoked.

Note: This page provides command reference for the rotate-key command. For comprehensive workflows and best practices, see API Key Management. For lifecycle and policy information, see API Key Lifecycle.

Usage

SignotaurTool.exe rotate-key [options]

Key Rotation Workflow

  1. Initiate Rotation - Call rotate-key with current API key
  2. Overlap Period - Both old and new keys remain valid (default: 7 days)
  3. Update Systems - Deploy new key to CI/CD systems during overlap
  4. Auto-Revocation - Old key is automatically revoked after overlap (optional)

Enables zero-downtime key rotation across distributed build systems.

Options

Authentication

Exactly one of --api-key or --api-key-file may be specified. If neither is provided, the API key is read from the environment variable (default: SIGNOTAUR_API_KEY, or the name specified via --api-key-name).

  • -a, --api-key <APIKey>

    Signotaur API key with ApiKeyRotation role and ownership of the key being rotated.

  • --af, --api-key-file <Path>

    Path to file containing API key (alternative to --api-key). The file can be a plain text file containing just the API key, or a dotenv file with SIGNOTAUR_API_KEY=<key> format.

  • --akn, --api-key-name <VarName>

    Specifies the variable name used when reading the API key from a dotenv file or environment variable (default: SIGNOTAUR_API_KEY).

  • -s, --sign-server <URL>

    Signotaur server URL. Required unless provided via the SIGNOTAUR_SERVER environment variable or configuration file.

Server URL Resolution:

The server URL can be provided via:

  1. --sign-server (command line argument)
  2. SIGNOTAUR_SERVER environment variable
  3. Configuration file (signServer key)

Rotation Settings

  • -o, --overlap-days <Days>

    Number of days both old and new keys remain valid (default: 7, range: 0–30). A value of 0 schedules the old key for immediate revocation. During any overlap period, compromise of the old key remains possible until it is revoked.

  • --nar, --no-auto-revoke

    Disable automatic revocation of the old key after the overlap period. The old key will remain valid indefinitely unless manually revoked. To manually revoke a key, navigate to the Signotaur Web UI → API Keys page, locate the old key, and click the "Revoke" button. Use this option when you need manual control over key lifecycle or have custom revocation workflows.

Output Destination (Optional - choose one)

Only one of --write-key-file, --write-env-file, or --emit-secret may be specified. If no output option is specified, the new API key is written to stdout.

  • --wk, --write-key-file <Path>

    Write new API key to a plain text file (mutually exclusive with --write-env-file and --emit-secret). The file will be created with secure permissions (Windows ACL owner-only read/write).

  • --we, --write-env-file <Path>

    Write new API key to a dotenv file as <varName>=<key> (mutually exclusive with --write-key-file and --emit-secret).

  • --wn, --write-env-var-name <VarName>

    Variable name when writing to dotenv file (default: SIGNOTAUR_API_KEY). Only used with --write-env-file. This option can only be used with --write-env-file.

  • -e, --emit-secret <Sink>

    Emit new API key to stdout in a CI/CD-specific format (mutually exclusive with --write-key-file and --write-env-file). This allows integration with various CI/CD platforms that can capture command output.

    ⚠ The secret is written to stdout. Ensure your CI logs are masked or redacted appropriately.

    Supported Formats:

    • continua:serverVar=NAME - Continua CI server variable format
    • continua:buildVar=NAME - Continua CI build variable format
    • template:CUSTOM_FORMAT - Custom template using variables (see below)

    Template Variables:

    • {{secret}} - Full API key
    • {{keyId}} - New key ID (integer)
    • {{expiry}} - Expiration date (ISO 8601)
    • {{overlapEnd}} - Overlap end date (ISO 8601)
    • {{name}} - Key name from server

    Example Templates:

    • template:SIGNOTAUR_API_KEY={{secret}}
    • template:export SIGNOTAUR_API_KEY={{secret}}
    • template:{"key":"{{secret}}","expires":"{{expiry}}"}

Miscellaneous

  • --au, --allow-untrusted

    Allow connecting to a Signotaur server bound to an untrusted or invalid certificate. Warning: This disables TLS certificate validation and should only be used in development or controlled environments.

Examples

  1. Basic rotation (logs new key to console):

    SignotaurTool.exe rotate-key --api-key "current-key" -s https://signotaur.example.com

  2. Rotate and update stored key file:

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

  3. Rotate with custom overlap period:

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

  4. Rotate without auto-revocation (manual control):

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

  5. Rotate and emit for Continua CI:

    SignotaurTool.exe rotate-key --api-key-file %USERPROFILE%\.signotaur\api_key.txt -s https://signotaur.example.com --emit-secret "continua:serverVar=SignotaurApiKey"

  6. Rotate and write to dotenv file:

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

  7. Custom template:

    SignotaurTool.exe rotate-key --api-key-file %USERPROFILE%\.signotaur\api_key.txt -s https://signotaur.example.com --emit-secret "template:SIGNOTAUR_API_KEY={{secret}}"

Authorization

The rotate-key command always rotates the API key you provide for authentication. A user may rotate only their own API keys, and only if they have the ApiKeyRotation role assigned. Users cannot rotate API keys belonging to other users.

The command generates a new key and returns it, while scheduling the old key for automatic revocation after the overlap period (unless --no-auto-revoke is specified).

Rotation Tracking

Each rotated key maintains an audit trail:

  • rotated_from_key_id - Links new key to original key
  • rotation_timestamp_utc - When the rotation occurred
  • auto_revoke_old_key_utc - When automatic revocation will occur (if enabled)

This provides full lineage tracking for compliance and auditing purposes.

CI/CD Examples

Continua CI

Set as server variable (persistent across builds):

SignotaurTool.exe rotate-key --api-key-file %SIGNOTAUR_KEY_FILE% -s %SERVER_URL% --emit-secret "continua:serverVar=SignotaurApiKey"

Set as build variable (current build only):

SignotaurTool.exe rotate-key --api-key-file %SIGNOTAUR_KEY_FILE% -s %SERVER_URL% --emit-secret "continua:buildVar=SignotaurApiKey"

See Continua CI Custom Log Messages for more details on variable types.

Jenkins

SignotaurTool.exe rotate-key --api-key-file %USERPROFILE%\.signotaur\api_key.txt -s https://signotaur.example.com --write-key-file %USERPROFILE%\.signotaur\api_key.txt
REM Jenkins will use the updated file on next build

Security Best Practices

  • ✓ Use --api-key-file or environment variable instead of --api-key
  • ✓ Rotate keys regularly (e.g., every 60-90 days or immediately on suspected compromise)
  • ✓ Use appropriate overlap period for your deployment frequency
  • ✓ Enable auto-revocation for automatic cleanup
  • ✓ Monitor rotation events in server audit logs
  • ✗ Don't use --no-auto-revoke unless you have manual revocation processes
  • ✗ Don't set excessively long overlap periods

CI/CD Integration

For comprehensive guidance on integrating API key rotation into your CI/CD pipelines, see CI/CD Integration Best Practices.

Key principles:

  • Run rotation on a scheduled maintenance pipeline (monthly/quarterly), not on every build
  • Regular builds should consume the current key using sign with --fail-if-expiring-within
  • Scheduled rotation pipelines rotate the key using rotate-key with appropriate overlap
  • Use the overlap period to update your CI/CD systems without service interruption

Duration Format

The --overlap-days option accepts integer values representing days (examples):

  • 0 (schedules the old key for immediate revocation)
  • 1
  • 7 (default)
  • 14
  • 30 (maximum)

Exit Codes

  • 0 (Success): Key rotation completed successfully
  • 1 (Failure): General error (e.g., authentication failed, server unreachable)
  • 2 (Unauthorized): API key does not belong to a valid user or the user lacks the ApiKeyRotation role.
  • 3 (Invalid Overlap): Overlap period must be between 1 and 30.

Troubleshooting

"Unauthorized" Error

Ensure the API key maps to a valid user and that the user has the ApiKeyRotation role assigned on the server.

Old Key Not Revoked

Check if --no-auto-revoke was used. Without this flag, the server background service automatically revokes the old key after the overlap period expires. The service runs hourly.

See Also

  • CI/CD Integration Best Practices - Detailed CI/CD integration patterns
  • Auth Command - Storing API keys securely
  • Sign Command - Using API keys for signing
  • API Key Management - Complete API key lifecycle
  • Server Admin - Users - Managing API keys via Web UI