# mcias-client (Python)

Python client library for the [MCIAS](../../README.md) identity and access management API.

## Requirements

- Python 3.11+
- `httpx >= 0.27`

## Installation

```sh
pip install .
# or in development mode:
pip install -e ".[dev]"
```

## Quick Start

```python
from mcias_client import Client

# Connect to the MCIAS server.
with Client("https://auth.example.com") as client:
    # Authenticate.
    token, expires_at = client.login("alice", "s3cret")
    print(f"token expires at {expires_at}")

    # The token is stored in the client automatically.
    accounts = client.list_accounts()

    # Revoke the token when done (also called automatically on context exit).
    client.logout()
```

## Custom CA Certificate

```python
client = Client(
    "https://auth.example.com",
    ca_cert_path="/etc/mcias/ca.pem",
)
```

## Error Handling

All methods raise typed exceptions on error:

```python
from mcias_client import (
    MciasAuthError,
    MciasForbiddenError,
    MciasNotFoundError,
    MciasInputError,
    MciasConflictError,
    MciasServerError,
)

try:
    client.login("alice", "wrongpass")
except MciasAuthError as e:
    print(f"auth failed ({e.status_code}): {e.message}")
except MciasForbiddenError as e:
    print(f"forbidden: {e.message}")
except MciasNotFoundError as e:
    print(f"not found: {e.message}")
except MciasInputError as e:
    print(f"bad input: {e.message}")
except MciasConflictError as e:
    print(f"conflict: {e.message}")
except MciasServerError as e:
    print(f"server error {e.status_code}: {e.message}")
```

All exception types are subclasses of `MciasError`, which has attributes:
- `status_code: int` — HTTP status code
- `message: str` — server error message

## Thread Safety

`Client` is **not** thread-safe. Each thread should use its own `Client`
instance.

## Running Tests

```sh
pip install -e ".[dev]"
pytest tests/ -q
mypy mcias_client/ tests/
ruff check mcias_client/ tests/
```