> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Complete reference for HopX CLI authentication commands - login, logout, status, validate, and API key management. Includes OAuth login, API key creation, and authentication verification.

Manage authentication for the HopX CLI using the `auth` command. Authenticate via OAuth, manage API keys, and verify authentication status.

## Command Syntax

```bash theme={null}
hopx auth <subcommand> [options]
```

## Subcommands

### `login`

Authenticate with HopX via browser OAuth.

**Syntax:**

```bash theme={null}
hopx auth login [OPTIONS]
```

**Options:**

* `--provider TEXT` - OAuth provider: `GoogleOAuth`, `GitHubOAuth` (default: `GoogleOAuth`)
* `--no-browser` - Headless mode: manually paste callback URL (for servers without browsers)

**Examples:**

```bash theme={null}
# OAuth login with Google (default)
hopx auth login

# OAuth login with GitHub
hopx auth login --provider GitHubOAuth

# Headless mode (for servers/containers without browsers)
hopx auth login --no-browser
```

**Expected Output:**

```
✓ Authentication successful
✓ You can now create API keys with 'hopx auth keys create'
```

**Exit Codes:**

* `0` - Success
* `1` - Authentication failed
* `5` - Timeout

### `logout`

Log out and clear stored credentials.

**Syntax:**

```bash theme={null}
hopx auth logout [OPTIONS]
```

**Examples:**

```bash theme={null}
# Log out
hopx auth logout
```

**Expected Output:**

```
✓ Logged out successfully
```

**Exit Codes:**

* `0` - Success

### `status`

Check authentication status.

**Syntax:**

```bash theme={null}
hopx auth status [OPTIONS]
```

**Examples:**

```bash theme={null}
# Check authentication status
hopx auth status
```

**Expected Output:**

```
✓ Authenticated
✓ API key: hopx_live_... (configured)
```

**Exit Codes:**

* `0` - Authenticated
* `3` - Not authenticated

### `validate`

Validate current API key.

**Syntax:**

```bash theme={null}
hopx auth validate [OPTIONS]
```

**Examples:**

```bash theme={null}
# Validate API key
hopx auth validate
```

**Expected Output:**

```
✓ API key is valid
```

**Exit Codes:**

* `0` - Valid
* `3` - Invalid or missing

### `refresh`

Refresh OAuth token.

**Syntax:**

```bash theme={null}
hopx auth refresh [OPTIONS]
```

**Examples:**

```bash theme={null}
# Refresh OAuth token
hopx auth refresh
```

**Expected Output:**

```
✓ Token refreshed successfully
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error

### `keys`

Manage API keys.

#### `keys list`

List all API keys.

**Syntax:**

```bash theme={null}
hopx auth keys list [OPTIONS]
```

**Examples:**

```bash theme={null}
# List API keys
hopx auth keys list
```

**Expected Output:**

```
┌──────────────┬─────────────────────┬──────────────┐
│ Name         │ Created             │ Last Used    │
├──────────────┼─────────────────────┼──────────────┤
│ my-key       │ 2025-01-27 10:00:00 │ 2025-01-27   │
│ production   │ 2025-01-26 09:00:00 │ 2025-01-27   │
└──────────────┴─────────────────────┴──────────────┘
```

#### `keys create`

Create a new API key.

**Syntax:**

```bash theme={null}
hopx auth keys create [OPTIONS]
```

**Options:**

* `--name TEXT` - API key name (auto-generated if not provided)

**Examples:**

```bash theme={null}
# Create API key with name
hopx auth keys create --name "my-key"

# Create with auto-generated name
hopx auth keys create
```

**Expected Output:**

```
✓ API key created: hopx_live_...
✓ Key stored securely
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error

#### `keys revoke`

Revoke an API key.

**Syntax:**

```bash theme={null}
hopx auth keys revoke KEY_ID [OPTIONS]
```

**Arguments:**

* `KEY_ID` - API key ID to revoke (required)

**Examples:**

```bash theme={null}
# Revoke API key
hopx auth keys revoke key_abc123
```

**Expected Output:**

```
✓ API key revoked: key_abc123
```

**Exit Codes:**

* `0` - Success
* `3` - Authentication error
* `4` - Key not found

#### `keys info`

Get information about an API key.

**Syntax:**

```bash theme={null}
hopx auth keys info KEY_ID [OPTIONS]
```

**Arguments:**

* `KEY_ID` - API key ID (required)

**Examples:**

```bash theme={null}
# Get API key info
hopx auth keys info key_abc123
```

**Expected Output:**

```
┌─────────────┬─────────────────────────────────────┐
│ Property    │ Value                               │
├─────────────┼─────────────────────────────────────┤
│ Name        │ my-key                               │
│ Created     │ 2025-01-27 10:00:00                 │
│ Last Used   │ 2025-01-27 12:00:00                 │
└─────────────┴─────────────────────────────────────┘
```

## Authentication Methods

### Method 1: OAuth Login (Recommended)

```bash theme={null}
# Login with browser
hopx auth login

# Create API key
hopx auth keys create --name "my-key"
```

### Method 2: Environment Variable

```bash theme={null}
# Set API key
export HOPX_API_KEY="hopx_live_..."

# Verify
hopx auth status
```

### Method 3: Config File

API keys are automatically stored in `~/.hopx/credentials.yaml` after creation.

## Shell Scripting Examples

### Check Authentication Before Running Commands

```bash theme={null}
#!/bin/bash

# Check authentication
if ! hopx auth status > /dev/null 2>&1; then
    echo "Not authenticated. Please run 'hopx auth login'"
    exit 1
fi

# Proceed with commands
hopx sandbox create --template python
```

### Create and Use API Key

```bash theme={null}
#!/bin/bash

# Create API key
KEY_NAME="ci-$(date +%s)"
hopx auth keys create --name "$KEY_NAME"

# Use in script
export HOPX_API_KEY=$(hopx auth keys info "$KEY_NAME" --output json | jq -r '.key')
```

## Related

* **[CLI Quickstart](/cli/quickstart)** - Get started with CLI authentication
* **[CLI Installation](/cli/installation)** - Installation guide
* **[API Key Guide](/api-key)** - Complete API key documentation
* **[Configuration](/cli/commands/config)** - Configure CLI settings

## Next Steps

* Complete [CLI Quickstart](/cli/quickstart) to authenticate and create your first sandbox
* Learn about [Configuration](/cli/commands/config) to manage multiple profiles
* Review [API Key Guide](/api-key) for security best practices