xeroctl keys

Manage API keys for project authentication. Requires --frontend-url or XEROTIER_FRONTEND_URL. Part of the xeroctl CLI.

Overview

API keys authenticate requests to your project's inference endpoints. Each key carries a set of permission scopes, an optional endpoint restriction, an optional expiration date, optional IP filter rules, and optional rate quota settings.

The keys command uses a unified flag-based interface. The action is determined by which flag is present (--create, --delete, --rotate, --ip-filter, --quota). Only one action flag may be specified at a time.

Security: Key values are shown only once at creation or rotation. Save the key immediately -- it cannot be retrieved again.

Usage Pattern

bash
xeroctl keys # List API keys xeroctl keys <id> # Show key details xeroctl keys --create --name <n> --scopes <s> # Create a new key xeroctl keys <id> --delete # Delete a key xeroctl keys <id> --rotate # Rotate a key xeroctl keys <id> --ip-filter --allow <ip> # Update IP filter xeroctl keys <id> --quota --rpm <n> # Update quota

list

List all API keys for the project. This is the default action when no ID or action flag is given.

bash
xeroctl keys xeroctl keys --limit 50 xeroctl keys --after key_abc123

Options

Option Description
--limit <n> Maximum number of results
--after <cursor> Pagination cursor: ID to start after

Output columns: ID, NAME, PREFIX, SCOPES, ACTIVE, LAST_USED, EXPIRES.

get

Show full details of a specific API key including scopes, prefix, active state, last-used timestamp, expiration, and endpoint restriction (if any).

bash
xeroctl keys key_abc123 xeroctl keys key_abc123 -o json

create

Create a new API key. Both --name and --scopes are required.

bash
# Basic key for chat access xeroctl keys --create --name "Production App" --scopes chat,models # Key scoped to a specific endpoint xeroctl keys --create \ --name "CI Pipeline" \ --scopes chat,embeddings \ --endpoint my-endpoint # Key with expiration xeroctl keys --create \ --name "Temporary Key" \ --scopes chat \ --expires 2026-12-31T00:00:00Z # Full options xeroctl keys --create \ --name "Data Pipeline" \ --scopes chat,embeddings,models \ --endpoint my-endpoint \ --expires 2027-01-01T00:00:00Z

Options

Option Description
--name <name> Human-readable key name (required)
--scopes <scopes> Comma-separated scopes (required). See Scopes.
--endpoint <slug> Restrict key to a specific endpoint slug
--expires <date> Expiration date in ISO 8601 format (e.g., 2026-12-31T00:00:00Z)

delete

Delete an API key. The key is immediately invalidated. A confirmation prompt is shown by default.

bash
# With confirmation prompt xeroctl keys key_abc123 --delete # Skip confirmation xeroctl keys key_abc123 --delete --force # Dry run xeroctl keys key_abc123 --delete --dry-run

Options

Option Description
--force Skip the confirmation prompt
--dry-run Show what would be deleted without making changes

rotate

Rotate an API key, generating a new key value. The old key value is immediately invalidated. A confirmation prompt is shown by default.

bash
# With confirmation prompt xeroctl keys key_abc123 --rotate # Skip confirmation xeroctl keys key_abc123 --rotate --force

Options

Option Description
--force Skip the confirmation prompt
--dry-run Show what would happen without making changes

Immediate effect: The current key value is invalidated the moment rotation completes. Update any systems using the old key before rotating in production.

ip-filter

Update IP filter rules for a key. Specify allowed and/or blocked IP addresses and CIDR ranges. Both --allow and --block are repeatable.

bash
# Allow only private network traffic xeroctl keys key_abc123 --ip-filter \ --allow 10.0.0.0/8 \ --allow 192.168.0.0/16 # Block specific IP addresses xeroctl keys key_abc123 --ip-filter \ --block 203.0.113.5 \ --block 203.0.113.6 # Allow a range and block a specific IP xeroctl keys key_abc123 --ip-filter \ --allow 10.0.0.0/8 \ --block 10.0.0.99

Options

Option Description
--allow <ip> Allowed IP address or CIDR range (repeatable)
--block <ip> Blocked IP address or CIDR range (repeatable)
--dry-run Show what would be updated without making changes

quota

Update rate quota settings for a key. Set requests per minute and the quota window duration.

bash
# Set 1000 requests per minute xeroctl keys key_abc123 --quota --rpm 1000 # Set requests per window with custom window size xeroctl keys key_abc123 --quota --rpm 500 --window 120 # Dry run xeroctl keys key_abc123 --quota --rpm 200 --dry-run

Options

Option Description
--rpm <n> Requests per minute limit
--window <n> Quota window in seconds (overrides the per-minute semantics when set)
--dry-run Show what would be updated without making changes

Scopes

Scopes control which API operations the key is authorized to perform. Pass multiple scopes as a comma-separated list to --scopes.

Scope Description
chat Chat completions and Responses API
models List and inspect models
embeddings Embeddings API
files File upload and management
batch Batch API operations

Examples

Create a Production Key

bash
# Create key with multiple scopes xeroctl keys --create \ --name "Production API" \ --scopes chat,embeddings,models # The full key value is printed once -- save it immediately

Secure a Key with IP Filtering

bash
# Allow only your datacenter CIDR xeroctl keys key_abc123 --ip-filter --allow 203.0.113.0/24

Apply Rate Limits

bash
# Limit to 100 requests per minute xeroctl keys key_abc123 --quota --rpm 100 --window 60

Rotate a Compromised Key

bash
# Immediately rotate (no prompt) xeroctl keys key_abc123 --rotate --force # New key value is printed -- update your systems before proceeding

xeroctl CLI

Back to the main xeroctl reference.

Authentication

API key authentication and scopes reference.