Skip to main content

Need a powerful server for your projects?

Discover our offers

Démarrer avec l'API client

L'API client YorkHost vous permet de piloter vos services depuis vos scripts, votre CI ou un assistant IA (Claude, Cursor…). Elle est en bêta publique : le périmètre s'élargira, les routes existantes resteront stables.

Claude.ai, ChatGPT : pas besoin de clé

Pour connecter YorkHost à Claude.ai, Claude Desktop ou ChatGPT, ajoutez simplement le connecteur https://api.yorkhost.fr/client/mcp et connectez-vous à votre compte : voir Serveur MCP. Les clés API servent aux scripts, à la CI et aux clients MCP sans connexion par compte.

1. Activer la double authentification​

Les clés API sont réservées aux comptes protégés par la double authentification (A2F). Activez-la depuis votre espace client : Sécurité → Authentification à deux facteurs. Si vous la désactivez plus tard, vos clés cessent de fonctionner.

2. Créer une clé​

Dans votre espace client, ouvrez Clés API et cliquez sur Créer une clé :

  1. Donnez-lui un nom (« Claude Desktop », « CI GitHub »…).
  2. Choisissez un modèle de permissions ou cochez-les une à une. Donnez uniquement ce dont l'usage a besoin.
  3. Limitez-la à certains services si elle ne doit pas tout voir.
  4. Choisissez une expiration (90 jours par défaut) et, pour un script sur serveur fixe, une allowlist d'adresses IP.

La clé, de la forme yhk_client_v1_<id>_<secret>, n'est affichée qu'une seule fois. Copiez-la immédiatement. Si vous la perdez, révoquez-la et créez-en une nouvelle.

Vous recevez un e-mail à chaque création, modification ou révocation de clé.

3. Premier appel​

curl -H "Authorization: Bearer yhk_client_v1_..." \
  https://api.yorkhost.fr/client/v1/services

Réponse : la liste de vos services, avec leur id à utiliser dans les autres routes.

Réponses et erreurs​

CodeSignification
401Clé absente, invalide, expirée ou révoquée, ou double authentification inactive (code : missing_token, invalid_token, mfa_required).
403Permission manquante (missing_scope, le champ required_scope indique laquelle) ou adresse IP non autorisée (ip_not_allowed).
404Service inexistant, hors de la liste autorisée de la clé, ou appartenant à un autre compte.
429Limite atteinte ; l'en-tête Retry-After donne le délai en secondes.

Les erreurs sont au format {"error": "...", "code": "..."}. Les listes sont paginées avec ?page= et ?limit= (100 maximum).

Limites​

  • 120 lectures et 20 écritures par minute et par clé.
  • 10 redémarrages par minute, 5 créations de ticket et 10 réponses par minute.

Journal et sécurité​

  • Chaque requête (API ou MCP) apparaît dans le journal de la clé, dans votre espace client, pendant 90 jours : date, route ou outil, service, code de réponse, adresse IP.
  • Une clé compromise ? Révoquez-la depuis l'espace client : l'accès est coupé immédiatement. Changer votre mot de passe révoque aussi toutes vos clés.
  • Ne mettez jamais une clé dans un dépôt Git. Le format yhk_client_v1_ est reconnu par la détection de secrets de GitHub.