# Guide — Connecter une application externe à la Core-API

## Vue d'ensemble

```
App externe (ex: ManageApp)
  │
  │  X-API-Key + X-API-Secret (headers)
  ▼
Core-API
  └── Vérifie les scopes autorisés pour cette app
  └── Exécute la requête et retourne la réponse
```

La Core-API utilise un système de clés publique/secrète par application. Chaque app externe doit :
1. Être enregistrée dans la Core-API (obtenir ses clés)
2. Déclarer les routes qu'elle expose (pour la découverte)
3. Se voir accorder les scopes (routes Core-API) qu'elle a le droit d'appeler

---

## Côté Core-API — Configuration de l'application

### Étape 1 — Enregistrer l'application externe

```
POST /external-applications
```

**Body :**
```json
{
  "name": "K-Shop",
  "description": "...",
  "organization": "...",
  "website": "..."
}
```

**Réponse :**
```json
{
  "success": true,
  "message": "Application externe créée avec succès. Conservez les clés en sécurité.",
  "data": {
    "id": "cfd9cdd1-a410-4949-a9d8-b765823ea345",
    "name": "K-Shop",
    "public_key": "pk_ffd682047cd2e8c0b4ecfe87fc7577553d485cc1d553263e32afcb71d926",
    "secret_key": "sk_52b8b3112a1ee703b6461c9f89773169ffac1c8bc5177148dc4fd7f50ca1d2f2",
    "status": "active",
    "created_at": "2026-05-04T10:06:16.000000Z"
  }
}
```

> **Important :** conserver `public_key` et `secret_key` immédiatement. La `secret_key` ne sera plus accessible après cette réponse.

---

### Étape 2 — Déclarer les routes exposées par l'application

Cette étape documente les endpoints que l'application externe expose elle-même, afin qu'ils soient découvrables depuis la Core-API.

```
POST /external-api-configurations
```

**Body :**
```json
{
  "endpoints": [
    {
      "endpoint": "GET:/api/v1/licenses",
      "method": "GET",
      "path": "/api/v1/licenses",
      "module": "licenses"
    },
    {
      "endpoint": "GET:/api/v1/licenses/{license}/show/jwtKey",
      "method": "GET",
      "path": "/api/v1/licenses/{license}/show/jwtKey",
      "module": "licenses"
    },
    {
      "endpoint": "POST:/api/v1/licenses",
      "method": "POST",
      "path": "/api/v1/licenses",
      "module": "licenses"
    }
  ]
}
```

**Découvrir les routes disponibles par module :**

```
GET /external-api-configurations/discover
```

**Query params :**
```
?module=licenses
```

---

### Étape 3 — Accorder les scopes à l'application

Un scope = une route Core-API que l'application externe est autorisée à appeler.

```
POST /external-applications/{applicationId}/scopes
```

**Body :**
```json
{
  "scopes": [
    "GET:/api/v1/licenses",
    "POST:/api/v1/licenses",
    "GET:/api/v1/licenses/datatables",
    "GET:/api/v1/licenses/{license}/show",
    "PUT:/api/v1/licenses/{license}/update"
  ],
  "description": "Endpoints licences autorisés pour cette app"
}
```

> Le champ `applicationId` est le `data.id` retourné à l'étape 1.