API Key Lifecycle -- Create, Rotate, Revoke, and Secure

Who this is for: DevOps engineers managing API credentials, security teams enforcing key rotation policies, and developers setting up CI/CD pipelines with SWT3 integration.

1. Key Basics

Format	`axm_live_` + 32 random hex characters (48 chars total)
Storage	SHA-256 hashed. Raw key is never stored and cannot be recovered.
Shown Once	The raw key is displayed only at creation. Copy it immediately.
Max Per Tenant	5 active keys
Scope	Tenant-level. A key grants access to all endpoints for that tenant.
Expiration	Keys do not expire. They remain valid until explicitly revoked.

Critical: If you lose a key, it cannot be recovered. You must create a new key and update all systems that use the old one, then revoke the old key.

2. Creating Keys

Via Dashboard

Log in as an admin.
Go to Settings > API Keys.
Click Create Key.
Copy the key immediately. It will not be shown again.

Via API

curl -X POST https://sovereign.tenova.io/api/v1/keys \
  -H "Cookie: axiom_session=..."

# Response:
{
  "key": "axm_live_7f3a9b2c4d5e6f7890abcdef12345678",
  "prefix": "axm_live_7f3a****"
}

The prefix field is what appears in the dashboard list and audit logs (masked for security).

3. Key Security

Do

Store keys in environment variables: export SWT3_API_KEY=axm_live_...
Use a secret manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, Azure Key Vault)
Restrict access to keys on a need-to-know basis
Rotate keys on a regular schedule (e.g., quarterly) or immediately after personnel changes

Do Not

Commit keys to source control (add .env to .gitignore)
Embed keys in client-side code (JavaScript bundles, mobile apps)
Share keys via email, Slack, or unencrypted channels
Log keys in application output (mask them in logging middleware)

Pre-commit hook: Add a grep check to your pre-commit hooks to block commits containing axm_live_ or axm_trial_. This prevents accidental key exposure.

4. Rotation Without Downtime

API key rotation is zero-downtime because multiple keys can be active simultaneously (up to 5). Follow this sequence:

Create the New Key

Settings > API Keys > Create Key. Copy it. You now have 2 active keys.

Update Your Systems

Deploy the new key to your SDK configuration, CI/CD secrets, and any direct API integrations. The old key continues to work during this transition.

Verify

Confirm anchors are flowing with the new key. Check the Ledger page for new entries. Run a health check:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $NEW_KEY" \
  https://sovereign.tenova.io/api/v1/health

Revoke the Old Key

Once all systems are confirmed working with the new key, revoke the old one. This is immediate and irreversible.

Overlap period: Both keys work simultaneously for as long as you need. There is no rush to revoke the old key. Take the time to verify every integration before revoking.

5. Revoking Keys

Via Dashboard

Settings > API Keys > click the revoke button next to the key.

Via API

curl -X DELETE https://sovereign.tenova.io/api/v1/keys \
  -H "Cookie: axiom_session=..." \
  -H "Content-Type: application/json" \
  -d '{"id": "key_id_here"}'

What happens:

The key is deleted from the database immediately.
Any subsequent API call using the revoked key receives 401.
Existing anchors already written to the ledger are not affected.
The revocation is logged to the audit trail with the key prefix and the admin who performed it.

6. Key Prefixes

Prefix	Created By	Notes
`axm_live_`	Settings > API Keys (admin action)	Standard production key
`axm_trial_`	Pilot or trial tenant provisioning	Functionally identical to live
`axm_open_`	Self-serve signup (`/signup`)	Auto-generated at account creation. OPEN tier.

All three prefixes are functionally equivalent. The prefix is cosmetic and helps identify the key's origin in audit logs.

7. CI/CD Integration

GitHub Actions

# .github/workflows/witness.yml
env:
  SWT3_API_KEY: ${{ secrets.SWT3_API_KEY }}
  SWT3_TENANT_ID: ${{ secrets.SWT3_TENANT_ID }}

steps:
  - run: pip install swt3-ai
  - run: python -c "from swt3_ai import Witness; w = Witness(); w.flush()"

GitLab CI

# .gitlab-ci.yml
variables:
  SWT3_API_KEY: $SWT3_API_KEY   # set in Settings > CI/CD > Variables (masked)
  SWT3_TENANT_ID: $SWT3_TENANT_ID

Docker

# Pass as environment variable, never bake into the image
docker run -e SWT3_API_KEY="axm_live_..." my-app

Kubernetes

# Create a secret
kubectl create secret generic swt3-creds \
  --from-literal=api-key=axm_live_...

# Reference in deployment
env:
  - name: SWT3_API_KEY
    valueFrom:
      secretKeyRef:
        name: swt3-creds
        key: api-key

8. Troubleshooting

Lost key

Keys cannot be recovered (SHA-256 hashed storage). Create a new key, update all systems, then revoke the lost key to prevent unauthorized use.

401 "Invalid or revoked API key"

Check for leading/trailing whitespace in your environment variable.
Verify the key starts with axm_.
Check if the key was revoked (Settings > Audit Log, filter by "key_revoke").
Ensure the Authorization header format is exactly Bearer axm_... (capital B, one space).

Max key limit reached

You can have at most 5 active keys per tenant. Revoke unused keys to make room. Check which keys are still in use by reviewing last_used timestamps in Settings > API Keys.

Key works in curl but not in SDK

Verify the SDK is using the correct environment variable name (SWT3_API_KEY).
Some shells strip quotes from environment variables. Check: echo "$SWT3_API_KEY" | cat -A (should show no trailing ^M or whitespace).
If using a .env file, ensure there are no quotes around the value (some libraries handle this differently).

9. Audit Trail

All key management actions are logged to the SI-12 audit trail:

Action	Logged Fields
`key_create`	Key prefix, tenant ID, admin email, timestamp
`key_revoke`	Key ID, key prefix, tenant ID, admin email, timestamp

View the audit log at Settings > Audit Log. Filter by action type to see all key management events. This log is retained for the full retention period of your tier.