Skip to main content
/ Docs
Quickstart API SDKs

CLI: API Keys Management

Create, list, update, and manage API keys for programmatic access to Trix.

Updated

Overview

The keys command provides tools for managing API keys that enable programmatic access to the Trix API. You can create keys with different permissions, set expiration times, and manage their lifecycle.

Aliases: key, ak

Important: API key management requires user login (email/password authentication). If you're currently authenticated with an API key, you'll need to log in with your email and password first:

trix auth login --email [email protected]

Create API Keys

Create new API keys for programmatic access to your Trix account. Keys can be configured with different permissions and expiration times.

# Create a basic API key
trix keys create --name "Production API"

# Create with description
trix keys create --name "Dev Key" --description "Development environment"

# Create an admin key
trix keys create --name "Admin Key" --admin

# Create with expiration
trix keys create --name "Temp Key" --expires 720h  # 30 days
trix keys create --name "Short-lived" --expires 24h

# Interactive mode
trix keys create

Save your key immediately! The full API key is only shown once during creation. You won't be able to see it again. Store it securely.

Create Options

OptionDescription
--nameName for the API key (required)
--descriptionDescription of the key's purpose
--adminGrant account admin privileges
--expiresSet expiration duration (e.g., 720h, 30d)

List API Keys

View all API keys for your account, including their status, last usage, and creation date.

# List all keys
trix keys list

# Output as JSON
trix keys list -o json

# Filter with jq
trix keys list --jq '.[].name'
trix keys list --jq '[.[] | select(.is_active)]'
trix keys list --jq '[.[] | select(.is_account_admin)]'

Example output:

ID           NAME            PREFIX    ADMIN  ACTIVE  LAST USED        CREATED
key_abc123   Production API  gdb_prod  no     yes     2 hours ago      Jan 15, 2024
key_def456   Dev Key         gdb_dev   no     yes     5 minutes ago    Jan 20, 2024
key_ghi789   Admin Key       gdb_admin yes    yes     1 day ago        Jan 10, 2024

Update API Keys

Update properties of an existing API key, including description, active status, and admin privileges.

# Update description
trix keys update key_abc123 --description "Updated description"

# Enable/disable a key
trix keys update key_abc123 --enable
trix keys update key_abc123 --disable

# Grant admin privileges
trix keys update key_abc123 --admin

# Remove admin privileges
trix keys update key_abc123 --no-admin
At least one update flag must be provided (--description, --enable, --disable, --admin, or --no-admin).

Update Options

OptionDescription
--descriptionUpdate the key's description
--enableEnable the API key
--disableDisable the API key
--adminGrant account admin privileges
--no-adminRemove account admin privileges

Delete API Keys

Revoke an API key. This action cannot be undone. The key will immediately stop working.

# Delete a key (with confirmation)
trix keys delete key_abc123

# Skip confirmation
trix keys delete key_abc123 --yes
Deleting an API key immediately revokes access. Any applications using this key will fail authentication. Make sure to update your applications before deleting keys they depend on.

Command Reference

keys Commands

CommandDescription
createCreate a new API key
listList all API keys
update <key-id>Update an API key
delete <key-id>Delete (revoke) an API key

Common Examples

Initial Setup

# Create your first API key
trix keys create --name "Production" --description "Main production API key"

# Save the key securely
# The full key (gdb_xxx...) will only be shown once

# Use the key for authentication
export TRIX_API_KEY=gdb_your_key_here

# Test the key
trix whoami

Key Rotation

# Create a new key
NEW_KEY=$(trix keys create --name "Production v2" -o json | jq -r '.key')

# Update your applications to use the new key
# ...

# After verifying the new key works, delete the old one
trix keys delete key_old123 --yes

Temporary Access

# Create a short-lived key for temporary access
trix keys create --name "Contractor Access" --expires 168h --description "7-day access for external contractor"

# Create a key for testing
trix keys create --name "Test Key" --expires 24h

Audit Keys

# List all keys
trix keys list

# Find inactive keys
trix keys list --jq '[.[] | select(.is_active == false)]'

# Find admin keys
trix keys list --jq '[.[] | select(.is_account_admin)]'

# Export for audit
trix keys list -o json > keys-audit-$(date +%Y%m%d).json

Manage Permissions

# Create a read-only key (standard key without admin)
trix keys create --name "Read Only"

# Create an admin key
trix keys create --name "Admin Access" --admin

# Upgrade a key to admin
trix keys update key_abc123 --admin

# Downgrade from admin
trix keys update key_abc123 --no-admin

# Disable a key temporarily (without deleting)
trix keys update key_abc123 --disable

# Re-enable later
trix keys update key_abc123 --enable

Best Practices

Security

  • Never commit API keys to version control
  • Use environment variables or secure secret management tools
  • Rotate keys regularly (every 90 days recommended)
  • Use separate keys for different environments (dev, staging, prod)
  • Set expiration dates on temporary keys
  • Grant admin privileges sparingly

Organization

  • Use descriptive names that indicate the key's purpose
  • Add detailed descriptions to track key usage
  • Regularly audit your keys and delete unused ones
  • Document which applications use which keys

Monitoring

# Check when keys were last used
trix keys list

# Identify potentially compromised keys
trix keys list --jq '[.[] | select(.last_used_at == null)]'

# List keys created more than 90 days ago
trix keys list --jq '[.[] | select(.created_at < "'$(date -u -d '90 days ago' +%Y-%m-%dT%H:%M:%SZ)'")]'

Next Steps