# Authentik Tool Suite

Manage Authentik identity provider (SSO, users, groups, applications, flows) via CLI.

## Prerequisites

- `jq` installed
- Authentik credentials in `~/.config/mosaic/credentials.json` (or `$MOSAIC_CREDENTIALS_FILE`)
- Required fields: `authentik.url`, `authentik.username`, `authentik.password`

## Authentication

Scripts use `auth-token.sh` to auto-authenticate via username/password and cache the API token at `~/.cache/mosaic/authentik-token`. The token is validated on each use and refreshed automatically when expired.

For better security, create a long-lived API token in Authentik admin (Directory > Tokens) and set `$AUTHENTIK_TOKEN` in your environment — the scripts will use it directly.

## Scripts

| Script            | Purpose                                    |
| ----------------- | ------------------------------------------ |
| `auth-token.sh`   | Authenticate and cache API token           |
| `user-list.sh`    | List users (search, filter by group)       |
| `user-create.sh`  | Create user with optional group assignment |
| `group-list.sh`   | List groups                                |
| `app-list.sh`     | List OAuth/SAML applications               |
| `flow-list.sh`    | List authentication flows                  |
| `admin-status.sh` | System health and version info             |

## Common Options

All scripts support:

- `-f json` — JSON output (default: table)
- `-h` — Show help

## API Reference

- Base URL: `https://auth.diversecanvas.com`
- API prefix: `/api/v3/`
- OpenAPI schema: `/api/v3/schema/`
- Auth: Bearer token in `Authorization` header

## Examples

```bash
# List all users
~/.config/mosaic/tools/authentik/user-list.sh

# Search for a user
~/.config/mosaic/tools/authentik/user-list.sh -s "alice"

# Create a user in the admins group
~/.config/mosaic/tools/authentik/user-create.sh -u newuser -n "New User" -e new@example.com -g admins

# List OAuth applications as JSON
~/.config/mosaic/tools/authentik/app-list.sh -f json

# Check system health
~/.config/mosaic/tools/authentik/admin-status.sh
```
