API Key Management

Overview

API keys are tr_-prefixed tokens used for authenticating CLI and API requests to the Truss platform. They provide a secure way to integrate Truss into automated workflows, CI/CD pipelines, and third-party tooling.

Security

  • Keys are SHA-256 hashed at rest — the plaintext value is shown exactly once at creation. If lost, a new key must be generated.
  • API keys are scoped to Developer (level 1) RBAC permissions by default.
  • Treat API keys like passwords: rotate them regularly and never commit them to version control.

Managing API Keys

Via Dashboard

  1. Navigate to Settings → API Keys
  2. Click Create Key
  3. Copy the plaintext key immediately — it will not be shown again

Via CLI

The truss auth login command auto-configures an API key on first login. To view the stored key:

truss config list

Via API

Create a key:

curl -X POST http://localhost:4000/api-keys \
  -H "Authorization: Bearer <session_token>"

List keys:

curl http://localhost:4000/api-keys \
  -H "Authorization: Bearer <session_token>"

Delete a key:

curl -X DELETE http://localhost:4000/api-keys/:keyId \
  -H "Authorization: Bearer <session_token>"

Environment Variable Override

The TRUSS_API_KEY environment variable overrides the configured key for a single command:

TRUSS_API_KEY=tr_abc123 truss mandate list

This is useful for temporary or scoped access in scripts and CI environments.

Best Practices

  • Rotate keys regularly — establish a rotation schedule (e.g., every 90 days)
  • Use separate keys per environment — distinct keys for development, staging, and production
  • Never commit keys to git — use environment variables or secret management tools
  • Delete unused keys — revoke access for decommissioned services or team members
PreviousReferenceNextGlossary