# Agents IA sur Buuyers

Buuyers est une place de marché de services : un utilisateur décrit un besoin (un
métier, une commune), les professionnels répondent — question de clarification ou
devis chiffré. Un agent (Claude, ChatGPT, un script) peut publier une demande et
suivre les réponses au nom d'un utilisateur, jamais sans son autorisation explicite.

Présentation en français courant, pour un humain : https://buuyers.com/agents

## S'authentifier (OAuth 2.1)

Buuyers est le serveur d'autorisation. Un agent obtient un jeton scellé par
l'utilisateur lui-même au moment de l'autoriser — jamais par mot de passe, jamais
sans son consentement explicite.

Métadonnées du serveur (RFC 8414) : GET https://buuyers.com/.well-known/oauth-authorization-server

Un agent doit d'abord être enregistré par Buuyers (liste blanche, pas
d'auto-enregistrement) : écrivez-nous depuis https://buuyers.com/contact avec le nom de
votre agent et l'URI de redirection à déclarer.

Deux flux, selon que votre agent a un navigateur avec callback ou non :

### 1. Redirection + PKCE (agent avec callback web)

```
GET https://buuyers.com/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=…&code_challenge=…&code_challenge_method=S256&state=…
```
L'utilisateur se connecte s'il ne l'est pas encore, puis autorise ou refuse sur un
écran qui nomme votre agent et les portées demandées.
```
POST https://buuyers.com/oauth/token
grant_type=authorization_code&code=…&code_verifier=…&redirect_uri=…&client_id=…
```
→ un jeton d'accès (1h) et un refresh token (30 jours).

### 2. Device code (agent sans navigateur — script local, agent d'un professionnel)

```
POST https://buuyers.com/oauth/device_authorization
client_id=…&scope=…
```
→ `device_code`, `user_code`, `verification_uri`. Affichez à l'utilisateur :
« Allez sur https://buuyers.com/activer et entrez CE-CODE ».
```
POST https://buuyers.com/oauth/token
grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=…&client_id=…
```
→ répond `authorization_pending` tant que l'utilisateur n'a pas validé, puis le jeton.

## Portées

| Portée | État | Donne accès à |
|---|---|---|
| `lire:mon-profil` | active | Lire votre identité de membre (pseudo, portées accordées, plafond) |
| `lire:mes-demandes` | réservée | Lire vos demandes publiées et les réponses reçues |
| `publier:discussion` | réservée | Publier une discussion en votre nom |
| `publier:devis` | réservée | Publier une demande de devis en votre nom |

Une portée « réservée » existe déjà dans le protocole (un client peut s'y
enregistrer) mais aucun point d'entrée ne l'honore encore — ne construisez pas
contre elle aujourd'hui, cette page sera mise à jour dès qu'elle s'active.

## Agir

- Identité du mandat (portées accordées, plafond, compteur) :
  `GET https://buuyers.com/api/v1/me` avec `Authorization: Bearer <jeton>` — portée `lire:mon-profil`.
- Publier une demande, lire les métiers et communes : en construction — pas encore
  d'endpoint, revenez consulter cette page.

## Révocation

L'utilisateur révoque l'accès de votre agent à tout moment depuis
« Mon compte → Agents connectés » (ou, côté Buuyers, depuis Admin → Agents IA si
votre agent lui-même est désactivé). Un jeton dont le mandat est révoqué cesse de
fonctionner à la requête suivante — pas besoin d'attendre son expiration.