# Installation Guide

## Requirements

- Python 3.10 or higher
- pip or uv package manager

## Installation

### Using pip

```bash
pip install concentriq-ls-client
```

### Using uv (Recommended)

```bash
uv add concentriq-ls-client
```

### From Source

```bash
git clone https://github.com/Proscia/concentriq-ls-python-client.git
cd concentriq-ls-python-client
uv sync --all-extras
```

## Authentication

The client supports four authentication methods. Choose the one that best fits your use case.

### API Key Authentication (Recommended)

API keys provide secure, long-lived authentication without exposing user credentials.

```python
from concentriq import ConcentriqClient
from concentriq.auth import ApiKeyAuth

client = ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=ApiKeyAuth(api_key="your-api-key-here")
)
```

**Generating an API Key:**

```python
# First authenticate with username/password
from concentriq.auth import BasicAuth

temp_client = ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=BasicAuth(username="user@example.com", password="password")
)

# Generate API key
response = temp_client.v3.auth.create_api_key()
api_key = response["apiKey"]
print(f"Your API key: {api_key}")

# Now use API key for subsequent requests
client = ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=ApiKeyAuth(api_key=api_key)
)
```

### Basic Authentication

Use username and password for initial setup or testing.

```python
from concentriq.auth import BasicAuth

client = ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=BasicAuth(
        username="user@example.com",
        password="your-password"
    )
)
```

### JWT Bearer Token

Use JWT tokens for short-lived, secure authentication.

```python
from concentriq.auth import JWTAuth

client = ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=JWTAuth(token="eyJhbGci...")
)
```

**Creating a JWT Token:**

```python
# First authenticate with basic auth
from concentriq.auth import BasicAuth

temp_client = ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=BasicAuth(username="user@example.com", password="password")
)

# Create JWT token
response = temp_client.v3.auth.create_token()
jwt_token = response["token"]

# Use JWT token
client = ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=JWTAuth(token=jwt_token)
)
```

### Session Cookie

Use existing session cookies from browser sessions.

```python
from concentriq.auth import SessionAuth

client = ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=SessionAuth(session_cookie="s%3Asession-id...")
)
```

## Client Configuration

### Context Manager (Recommended)

Using a context manager ensures proper cleanup of HTTP connections:

```python
from concentriq import ConcentriqClient
from concentriq.auth import ApiKeyAuth

with ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=ApiKeyAuth(api_key="your-key")
) as client:
    # Client automatically closes connections when exiting context
    image_sets = client.v1.image_sets.list()
```

### Manual Management

```python
client = ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=ApiKeyAuth(api_key="your-key")
)

try:
    image_sets = client.v1.image_sets.list()
finally:
    client.close()  # Manually close connections
```

## Environment Variables

Store credentials securely using environment variables:

```bash
# .env file
CONCENTRIQ_BASE_URL=https://app.concentriq.com
CONCENTRIQ_API_KEY=your-api-key-here
```

```python
import os
from concentriq import ConcentriqClient
from concentriq.auth import ApiKeyAuth

client = ConcentriqClient(
    base_url=os.getenv("CONCENTRIQ_BASE_URL"),
    auth=ApiKeyAuth(api_key=os.getenv("CONCENTRIQ_API_KEY"))
)
```

## Verifying Installation

Test your installation and authentication:

```python
from concentriq import ConcentriqClient
from concentriq.auth import ApiKeyAuth

with ConcentriqClient(
    base_url="https://app.concentriq.com",
    auth=ApiKeyAuth(api_key="your-key")
) as client:
    # V3 whoami returns current user info
    user_info = client.v3.auth.whoami()
    print(f"Authenticated as user ID: {user_info['userId']}")
    print(f"Permissions: {len(user_info['roleRules'])} role rules")
```

## Troubleshooting

### Authentication Errors

```python
from concentriq.exceptions import AuthenticationError

try:
    client = ConcentriqClient(...)
    client.v1.image_sets.list()
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
    # Check your credentials and try again
```

### Connection Errors

```python
try:
    client = ConcentriqClient(base_url="https://wrong-url.com", ...)
except Exception as e:
    print(f"Connection error: {e}")
    # Verify base_url is correct
```

### SSL/TLS Issues

For self-signed certificates or internal instances:

```python
# Note: Not recommended for production
import httpx

client = ConcentriqClient(
    base_url="https://internal.concentriq.com",
    auth=ApiKeyAuth(api_key="your-key"),
    # Custom httpx client with SSL verification disabled
    http_client=httpx.Client(verify=False)
)
```

## Next Steps

- **[Usage Guide](usage.md)** - Learn how to use the V1, V2, and V3 APIs
- **[API Reference](api-reference.md)** - Complete method documentation
