Skip to main content

Manage secrets

This guide walks through managing secrets throughout their lifecycle: creation, listing, version inspection, rotation, audited revealing, and deletion.

Prerequisites​

  • Access to a Crusoe AI Platform project.
  • Project membership is required to list and inspect secrets.
  • Project administrator role is required to reveal secret values or delete secrets.

Set your API environment variables:

export CAI_API="https://api.codyhill.dev"
export CAI_PROJECT="<your-project-id>"
export CAI_TOKEN="<your-api-key-or-session-token>"

1. Create a secret​

Secrets are created by sending values via standard input, files, or Console UI.

  • Naming Rules: 1–63 characters (letters, numbers, -, _), starting with an alphanumeric character.
  • Value Limit: Up to 64 KiB per secret value.
# Pipe a secret value safely without exposing it in shell history
printf %s "$OPENAI_KEY" | platformctl secrets put openai-api-key

Or upload from a file:

platformctl secrets put tls-chain --value-file ./chain.pem

Output:

created openai-api-key at version 1

2. List secrets​

List all secret metadata in your project. Values are never returned in list responses.

platformctl secrets list

Output:

NAME            VERSION  UPDATED
openai-api-key  1        2026-08-12T09:14:03Z

3. Inspect secret metadata and history​

Inspect version history and bound workloads for a secret.

platformctl secrets show openai-api-key

View version history table:

platformctl secrets versions openai-api-key

Output:

VERSION  CREATED               CURRENT  DESTROYED
1        2026-08-12T09:14:03Z  yes      no

4. Rotate a secret​

Updating a secret creates a new version while preserving older versions for bound workloads.

printf %s "$NEW_OPENAI_KEY" | platformctl secrets put openai-api-key

Output:

rotated openai-api-key at version 2
Apply After Rotation

After rotating a secret, re-apply bindings on your workloads so they pick up the latest version on their next deployment or revision roll.

5. Reveal a secret value (Audited Break-Glass)​

Revealing a secret value is an administrative action that logs an audit record with your identity, timestamp, and justification.

platformctl secrets reveal openai-api-key --reason "verifying key rotation"

6. Delete a secret​

Deleting a secret permanently destroys all stored versions. Secrets cannot be deleted while actively bound to workloads.

platformctl secrets delete openai-api-key

Next steps​