# API — smart-ide-global-api

Écoute par défaut : **`127.0.0.1:37149`**. Configuration : `services/smart-ide-global-api/.env.example`, agrégat [config/services.local.env.example](../../config/services.local.env.example).

## Rôle

Agrégateur HTTP **interne** : reçoit les requêtes authentifiées par `Authorization: Bearer <GLOBAL_API_INTERNAL_TOKEN>` (fourni par `smart-ide-sso-gateway`), relaie vers chaque micro-service avec son **jeton technique** et propage les en-têtes `X-OIDC-Sub` / `X-OIDC-Email` lorsqu’ils sont présents.

Les navigateurs et applications utilisateur ne doivent **pas** appeler ce port directement : passer par la **passerelle SSO** (`/proxy/<clé>/...`).

## Authentification

| Route | Auth |
|-------|------|
| `GET /health` | Aucune |
| Toutes les autres | `Authorization: Bearer` égal à `GLOBAL_API_INTERNAL_TOKEN` |

## Endpoints

### `GET /health`

Réponse `200` : `{ "status": "ok", "service": "smart-ide-global-api" }`.

### `GET /v1/upstreams`

 Liste les clés d’amont connues : `{ "upstreams": [ "orchestrator", ... ] }`. La passerelle SSO peut renvoyer un sous-ensemble (allowlist via `SSO_ALLOWED_UPSTREAMS`).

### Proxy — `ANY /v1/upstream/<upstream_key>/<path>`

- **`<upstream_key>`** : `orchestrator`, `repos_devtools`, `ia_dev_gateway`, `anythingllm_devtools`, `tools_bridge`, `langextract`, `regex_search`, `claw_proxy`, `local_office`.
- **`<path>`** : transmis à l’URL de base du service (ex. `/v1/upstream/orchestrator/v1/...` → `http://127.0.0.1:37145/v1/...`).
- **Corps** : relayé (limite `GLOBAL_API_MAX_BODY_BYTES`, défaut 32 MiB).
- **Erreurs** : `401` si Bearer interne absent ou incorrect ; `404` si clé inconnue ; `503` si jeton manquant pour l’amont (ex. `ORCHESTRATOR_TOKEN`, `LOCAL_OFFICE_API_KEY`, etc.).

## Journaux

Fichier **`.logs/global-api/access.log`** : lignes JSON (`ts`, `method`, `path`, `upstream`, `status`, `durationMs`, `oidcSub` si présent).

## Variables d’environnement

| Variable | Rôle |
|----------|------|
| `GLOBAL_API_HOST` / `GLOBAL_API_PORT` | Bind HTTP |
| `GLOBAL_API_INTERNAL_TOKEN` | Obligatoire — secret partagé avec la passerelle SSO |
| `GLOBAL_API_MAX_BODY_BYTES` | Taille max du corps |
| `SMART_IDE_MONOREPO_ROOT` | Racine monorepo pour `.logs/` (sinon déduction depuis le module) |

Jetons et hôtes des micro-services : mêmes noms que dans `config/services.local.env.example`.

## Source des amonts

Les clés et la résolution `host:port` / jetons sont définies dans le paquet partagé **`packages/smart-ide-upstreams/`** (`@4nk/smart-ide-upstreams`). Toute nouvelle clé d’amont doit y être ajoutée une seule fois, puis `npm run build` dans ce paquet et commit du répertoire `dist/`.

## Voir aussi

- [sso-gateway-api.md](./sso-gateway-api.md)
- [sso-gateway-service.md](../features/sso-gateway-service.md)