claude-plugins/infraestrutura/skills/authentik/SKILL.md

---
name: authentik
description: Gestão do Authentik SSO via API v3 — utilizadores, grupos, aplicações, providers, flows e eventos em auth.descomplicar.pt.
disable-model-invocation: true
---

# /authentik - Gestao Authentik via API v3

Gestao do Authentik SSO (auth.descomplicar.pt) via API REST directa com curl.

## Conexao

- **Base URL:** `https://auth.descomplicar.pt/api/v3`
- **Auth Header:** `Authorization: Bearer Sa4Zofsdm7UoMXrHRAZ4sIsvNIqCtEQ3uCZrsDg7kx3wDCKQqI0frlFuoUVS`
- **Painel Web:** https://auth.descomplicar.pt/if/admin/

## Template Base

Todas as chamadas usam este padrao:

```bash
curl -sk "https://auth.descomplicar.pt/api/v3/{ENDPOINT}" \
  -H "Authorization: Bearer Sa4Zofsdm7UoMXrHRAZ4sIsvNIqCtEQ3uCZrsDg7kx3wDCKQqI0frlFuoUVS" \
  -H "Content-Type: application/json"
```

Para POST/PUT/PATCH, adicionar `-X {METHOD} -d '{JSON}'`.

## Endpoints Principais

### Core - Users

| Operacao | Metodo | Endpoint |
|----------|--------|----------|
| Listar users | GET | `/core/users/` |
| Obter user | GET | `/core/users/{id}/` |
| Criar user | POST | `/core/users/` |
| Actualizar user | PATCH | `/core/users/{id}/` |
| Apagar user | DELETE | `/core/users/{id}/` |
| Pesquisar user | GET | `/core/users/?search={query}` |
| User por username | GET | `/core/users/?username={name}` |
| Desactivar user | PATCH | `/core/users/{id}/` com `{"is_active": false}` |
| Password user | POST | `/core/users/{id}/set_password/` com `{"password": "..."}` |
| Recovery link | POST | `/core/users/{id}/recovery/` |

**Campos user (POST/PATCH):**
```json
{
  "username": "nome.apelido",
  "name": "Nome Completo",
  "email": "email@dominio.pt",
  "is_active": true,
  "groups": ["uuid-grupo"],
  "attributes": {"chave": "valor"}
}
```

### Core - Groups

| Operacao | Metodo | Endpoint |
|----------|--------|----------|
| Listar groups | GET | `/core/groups/` |
| Criar group | POST | `/core/groups/` |
| Actualizar group | PATCH | `/core/groups/{id}/` |
| Apagar group | DELETE | `/core/groups/{id}/` |
| Adicionar user a group | POST | `/core/groups/{id}/add_user/` com `{"pk": user_id}` |
| Remover user de group | POST | `/core/groups/{id}/remove_user/` com `{"pk": user_id}` |

### Core - Applications

| Operacao | Metodo | Endpoint |
|----------|--------|----------|
| Listar apps | GET | `/core/applications/` |
| Obter app | GET | `/core/applications/{slug}/` |
| Criar app | POST | `/core/applications/` |
| Actualizar app | PATCH | `/core/applications/{slug}/` |
| Apagar app | DELETE | `/core/applications/{slug}/` |

**Campos app:**
```json
{
  "name": "Nome App",
  "slug": "nome-app",
  "provider": provider_pk,
  "launch_url": "https://app.dominio.pt",
  "open_in_new_tab": true,
  "meta_description": "Descricao"
}
```

### Providers (OAuth2/Proxy/LDAP)

| Operacao | Metodo | Endpoint |
|----------|--------|----------|
| Listar OAuth2 | GET | `/providers/oauth2/` |
| Criar OAuth2 | POST | `/providers/oauth2/` |
| Listar Proxy | GET | `/providers/proxy/` |
| Criar Proxy | POST | `/providers/proxy/` |
| Listar LDAP | GET | `/providers/ldap/` |
| Listar todos | GET | `/providers/all/` |

**OAuth2 provider campos:**
```json
{
  "name": "Nome Provider",
  "authorization_flow": "flow-uuid",
  "invalidation_flow": "flow-uuid",
  "client_type": "confidential",
  "redirect_uris": "https://app.dominio.pt/callback"
}
```

### Flows

| Operacao | Metodo | Endpoint |
|----------|--------|----------|
| Listar flows | GET | `/flows/instances/` |
| Obter flow | GET | `/flows/instances/{slug}/` |
| Flow bindings | GET | `/flows/bindings/` |

### Events (Audit)

| Operacao | Metodo | Endpoint |
|----------|--------|----------|
| Listar events | GET | `/events/events/` |
| Filtrar por accao | GET | `/events/events/?action={action}` |
| Filtrar por user | GET | `/events/events/?username={user}` |
| Notifications | GET | `/events/notifications/` |
| System tasks | GET | `/events/system_tasks/` |

**Accoes comuns:** `login`, `login_failed`, `logout`, `user_write`, `model_created`, `model_updated`, `model_deleted`, `authorize_application`

### Tokens

| Operacao | Metodo | Endpoint |
|----------|--------|----------|
| Listar tokens | GET | `/core/tokens/` |
| Criar token | POST | `/core/tokens/` |
| Obter token | GET | `/core/tokens/{identifier}/` |
| Apagar token | DELETE | `/core/tokens/{identifier}/` |
| View key | GET | `/core/tokens/{identifier}/view_key/` |

### Outposts

| Operacao | Metodo | Endpoint |
|----------|--------|----------|
| Listar outposts | GET | `/outposts/instances/` |
| Health outpost | GET | `/outposts/instances/{id}/health/` |
| Service connections | GET | `/outposts/service_connections/all/` |

### Admin / Sistema

| Operacao | Metodo | Endpoint |
|----------|--------|----------|
| System info | GET | `/admin/system/` |
| Version | GET | `/admin/version/` |
| Workers | GET | `/admin/workers/` |
| Metrics | GET | `/admin/metrics/` |
| System tasks | GET | `/admin/system_tasks/` |

## Paginacao

Todos os endpoints de lista suportam:
- `?page=N` - pagina (default: 1)
- `?page_size=N` - itens por pagina (default: 20, max: depende)
- `?ordering=field` - ordenacao (prefixo `-` para descendente)
- `?search=query` - pesquisa texto livre

Resposta paginada:
```json
{
  "pagination": {"next": 2, "previous": 0, "count": 50, "current": 1, "total_pages": 3},
  "results": [...]
}
```

## Aplicacoes Actuais

| App | Slug | URL |
|-----|------|-----|
| Dashboard Descomplicar | dashboard-descomplicar | https://dash.descomplicar.pt |
| MCP Gateway | mcp-gateway | https://gateway.descomplicar.pt |

## Exemplos Praticos

### Listar todos os users
```bash
curl -sk "https://auth.descomplicar.pt/api/v3/core/users/" \
  -H "Authorization: Bearer Sa4Zofsdm7UoMXrHRAZ4sIsvNIqCtEQ3uCZrsDg7kx3wDCKQqI0frlFuoUVS"
```

### Criar user
```bash
curl -sk -X POST "https://auth.descomplicar.pt/api/v3/core/users/" \
  -H "Authorization: Bearer Sa4Zofsdm7UoMXrHRAZ4sIsvNIqCtEQ3uCZrsDg7kx3wDCKQqI0frlFuoUVS" \
  -H "Content-Type: application/json" \
  -d '{"username": "joao.silva", "name": "Joao Silva", "email": "joao@empresa.pt", "is_active": true}'
```

### Ver login events ultimas 24h
```bash
curl -sk "https://auth.descomplicar.pt/api/v3/events/events/?action=login&ordering=-created" \
  -H "Authorization: Bearer Sa4Zofsdm7UoMXrHRAZ4sIsvNIqCtEQ3uCZrsDg7kx3wDCKQqI0frlFuoUVS"
```

### Health check sistema
```bash
curl -sk "https://auth.descomplicar.pt/api/v3/admin/system/" \
  -H "Authorization: Bearer Sa4Zofsdm7UoMXrHRAZ4sIsvNIqCtEQ3uCZrsDg7kx3wDCKQqI0frlFuoUVS"
```

## Regras

1. SEMPRE confirmar com utilizador antes de criar/apagar users
2. NUNCA apagar users admin (akadmin)
3. Pesquisar duplicados antes de criar users (como CRM)
4. Passwords devem ter minimo 12 caracteres
5. Verificar groups existentes antes de associar