---
name: pysae-api
description: >
  Authenticate against the Pysae HTTP API (Auth0) and call any of its
  endpoints on dev or prod. Use when the user says /pysae-api, 'appelle l'API
  Pysae', 'requête sur l'API', 'call the Pysae API', 'connecte-toi à l'API',
  'login API Pysae', 'liste les groupes via l'API', 'crée/modifie X via
  l'API', or wants to read or mutate Pysae data through api.pysae.com /
  api.dev.pysae.com. Endpoints are discovered live from the OpenAPI spec — the
  skill never works from a hard-coded endpoint list.
argument-hint: "[login|spec|request] [--env dev|prod] ..."
allowed-tools:
  - Bash
---

Thin gateway over `pysae-ai-tools pysae api`. The CLI owns Auth0 login (PKCE / device flow), local token caching with silent refresh, live OpenAPI discovery (cached 1 day), and authenticated requests. Default environment is **dev** — only target **prod** when the user explicitly asks.

## Required tools

- `pysae-ai-tools`

The `pysae-ai-tools` CLI is always present in this environment (it is the harness for every Pysae skill). No external CLI or MCP is needed.

## How it works

The API exposes two OpenAPI documents per environment:

- `internal` (default) — the full surface (~330 operations).
- `public` — the smaller public subset.

Auth is Auth0 (OIDC). The CLI uses a dedicated **`pysae-ai-tools`** Auth0 native client and stores tokens at `~/.config/pysae-ai-tools/pysae-api-tokens.json` (mode `0600`), one entry per environment, refreshing the access token automatically via the rotating refresh token.

Credential precedence inside every `request`: `--api-key` / `$PYSAE_API_KEY` → `$PYSAE_API_TOKEN` → stored OAuth token. CI/headless callers should prefer an Api-Key or a pre-injected token.

## Workflow

**Always discover before calling.** Endpoints, paths and parameters change — never assume them.

1. **Find the endpoint** from the live spec:
   ```bash
   pysae-ai-tools pysae api spec --env dev --search <keyword>
   ```
   Then inspect one operation in full (params, request body, responses):
   ```bash
   pysae-ai-tools pysae api spec --env dev --path /api/v4/<...> --method get
   ```
   If a path the user mentions is absent, re-run with `--refresh` (the spec is cached 1 day) before concluding it does not exist:
   ```bash
   pysae-ai-tools pysae api spec --env dev --search <keyword> --refresh
   ```

2. **Authenticate** if `request` reports you are not logged in:
   ```bash
   pysae-ai-tools pysae api auth login --env dev          # opens a browser (PKCE)
   pysae-ai-tools pysae api auth login --env dev --device # headless / SSH (device code)
   pysae-ai-tools pysae api auth status --env dev
   ```
   In CI (`$CI` set) login uses the device flow automatically; for unattended runs, set `$PYSAE_API_KEY` or `$PYSAE_API_TOKEN` instead of logging in. Run login flows in the background and show the user the URL/code to authorize, then wait for completion.

3. **Call the endpoint**:
   ```bash
   pysae-ai-tools pysae api request GET /api/v4/groups --env dev
   pysae-ai-tools pysae api request GET /api/v4/groups -q limit=10 -q offset=0
   pysae-ai-tools pysae api request POST /api/v4/<...> --data '{"name":"x"}' --env dev
   pysae-ai-tools pysae api request PUT /api/v4/<...> --data @body.json --status
   ```

## Safety

- **dev by default.** Treat `--env prod` as production: confirm with the user before any mutating call (POST/PUT/PATCH/DELETE) against prod.
- Tokens are user-scoped — calls act with the logged-in user's permissions. Never print tokens; they live only in the `0600` cache file.

## Auth0 client id (already configured)

The dedicated `pysae-ai-tools` Auth0 native client (defined in `infra-cluster/modules/auth0`, dev + prod) is applied and its public client ids are baked into the CLI defaults — no setup is needed. To override (e.g. a new tenant), set `PYSAE_API_CLIENT_ID_DEV` / `PYSAE_API_CLIENT_ID_PROD` or run `pysae-ai-tools pysae api auth configure --env <env> --client-id <id>`.

For full options: `pysae-ai-tools pysae api --help` (and `spec|request|auth --help`).

$ARGUMENTS
