Compozy Symbol
ALPHA
DocsInstallGetting StartedFeaturesPricing
CoreCLI ReferenceSchema DefinitionAPI Reference

Authentication Commands

The `compozy auth` command group provides comprehensive authentication and API key management capabilities. These commands support both interactive TUI and automation-friendly JSON output modes.

Overview

compozy auth [command] [flags]

API Key Management

Generate, list, and revoke API keys for secure authentication

User Administration

Create and manage user accounts with role-based access control

Interactive TUI

User-friendly text interface for simplified operations

Automation Ready

JSON output format for seamless CI/CD and script integration

API Key Management

Generate API Key

Create a new API key for authenticating with the Compozy API:

# Interactive mode (TUI)
compozy auth generate

# With parameters
compozy auth generate --name "CI/CD Pipeline" --description "For automated deployments"

# With expiration date
compozy auth generate --name "Temporary Key" --expires "2024-12-31"

# JSON output for automation
compozy auth generate --name "API Integration" --output json

Flags

FlagDescriptionFormat
--nameName/description for the API keyString
--descriptionDetailed description of the API key usageString
--expiresExpiration dateYYYY-MM-DD
--outputOutput formatjson | table

List API Keys

View all API keys with their status and metadata:

# List all keys (TUI)
compozy auth list

# Sort by creation date
compozy auth list --sort created

# Filter by status
compozy auth list --status active

# JSON output
compozy auth list --output json

Flags

FlagDescriptionOptions
--sortSort by fieldcreated | name | expires
--statusFilter by statusactive | expired | revoked
--outputOutput formatjson | table

Revoke API Key

Revoke an existing API key:

# Interactive selection (TUI)
compozy auth revoke

# Revoke specific key
compozy auth revoke --key "amp_1234567890"

# JSON output
compozy auth revoke --key "amp_1234567890" --output json

Flags

FlagDescriptionFormat
--keyAPI key to revokeString
--outputOutput formatjson | table

User Management

Create User

Create a new user account:

# Interactive mode (TUI)
compozy auth create-user

# With parameters
compozy auth create-user --email "user@example.com" --name "John Doe"

# With role assignment
compozy auth create-user --email "admin@example.com" --name "Admin User" --role admin

# JSON output
compozy auth create-user --email "user@example.com" --name "John Doe" --output json

Flags

FlagDescriptionFormat/OptionsRequired
--emailUser's email addressEmailYes
--nameUser's full nameStringNo
--roleUser roleadmin | user | viewerNo
--outputOutput formatjson | tableNo

List Users

View all users in the system:

# List all users (TUI)
compozy auth list-users

# Filter by role
compozy auth list-users --role admin

# Sort by creation date
compozy auth list-users --sort created

# JSON output
compozy auth list-users --output json

Flags

FlagDescriptionOptions
--roleFilter by roleadmin | user | viewer
--sortSort by fieldcreated | email | name
--outputOutput formatjson | table

Update User

Update user information:

# Interactive mode (TUI)
compozy auth update-user

# Update specific user
compozy auth update-user --email "user@example.com" --name "Jane Doe"

# Change user role
compozy auth update-user --email "user@example.com" --role admin

# JSON output
compozy auth update-user --email "user@example.com" --role admin --output json

Flags

FlagDescriptionFormat/OptionsRequired
--emailUser's email address (to identify user)EmailYes
--nameNew name for the userStringNo
--roleNew role for the useradmin | user | viewerNo
--outputOutput formatjson | tableNo

Delete User

Remove a user from the system:

# Interactive selection (TUI)
compozy auth delete-user

# Delete specific user
compozy auth delete-user --email "user@example.com"

# Force deletion without confirmation
compozy auth delete-user --email "user@example.com" --force

# JSON output
compozy auth delete-user --email "user@example.com" --output json

Flags

FlagDescriptionFormat/Options
--emailEmail of user to deleteEmail
--forceSkip confirmation promptBoolean
--outputOutput formatjson | table

Authentication Flow

Initial Setup

When setting up Compozy for the first time:

1

Create the first admin user

Bootstrap the system with an initial administrator account
compozy auth create-user --email "admin@company.com" --name "Admin" --role admin
2

Generate an API key

Create an authentication key for API access
compozy auth generate --name "Admin API Key"
3

Set the API key in your environment

Configure the key for automatic authentication
export COMPOZY_API_KEY="amp_your_key_here"

Using API Keys

API keys can be provided in multiple ways:

export COMPOZY_API_KEY="amp_1234567890"
compozy workflow list

Best Practices

  • Key Rotation

    Regularly rotate API keys for security. Set expiration dates and create new keys before old ones expire.

  • Descriptive Names

    Use clear, descriptive names for API keys to identify their purpose and usage.

  • Role-Based Access

    Assign appropriate roles to users based on their responsibilities. Use viewer role for read-only access.

  • Audit Trail

    The auth system maintains an audit trail of all key usage. Use compozy auth list to review key activity.

  • Secure Storage

    Never commit API keys to version control. Use environment variables or secure secret management systems.

Next Steps

Configuration Commands
Manage global settings and project configuration
Workflow Commands
Execute, deploy, and monitor AI workflows
Project Commands
Initialize and manage Compozy projects

Development Commands

Development server commands for Compozy with hot reload and debugging

Configuration Commands

The `compozy config` command group provides comprehensive tools for managing, validating, and diagnosing your Compozy configuration. These commands ensure your setup is correct, optimized, and ready for production deployment.