API authentification

Le Showly REST API accepte deux types d'informations d'identification. Choisissez celui qui correspond à votre cas d'utilisation. L'URL de base est https://api.showly.ai — il n'y a pas de préfixe de version ni d'en-tête Api-Version.

Jetons d'accès personnels (PAT)

Pour : scripts ad hoc, automatisation personnelle.

Émission à partir de Profil → API jetons → Nouveau jeton. Un PAT est limité au espace de travail unique dans lequel il a été créé et porte les étendues que vous lui accordez au moment de la création. Traitez-le comme un identifiant.

GET /sites HTTP/1.1
Host: api.showly.ai
Authorization: Bearer sk_live_...

Les PAT utilisent le préfixe sk_live_ (ou sk_test_ pour le bac à sable). Ils:

• journal d'audit en tant que vous, l'utilisateur émetteur (bon pour la responsabilité).
• sont liés à un seul espace de travail ; créez-en un par espace de travail que vous automatisez.
• sont révoqués et alternés à partir de la même interface utilisateur. Pour CI, attribuez à chaque pipeline son propre PAT et faites-le pivoter selon un calendrier.

MCP jetons (flux de périphérique)

Pour : les agents et les clients MCP (Claude Code, Codex) qui agissent au nom d'un utilisateur.

Les clients agents s'authentifient avec un jeton MCP, obtenu via le flux d'autorisation de périphérique RFC 8628. Le jeton est émis pour l'utilisateur autorisant et porte les portées auxquelles il consent. Les jetons MCP utilisent le préfixe mcp_live_ (ou mcp_test_ pour le bac à sable).

Démarrez le flux en demandant un code d'appareil :

POST /oauth/device
Content-Type: application/x-www-form-urlencoded

client_id=<your-app>
&scope=site:read preview:create

L'utilisateur approuve la demande dans le navigateur (le flux de périphérique recherche/autorise les points de terminaison vers la page de vérification). Pendant ce temps, interrogez le point de terminaison du jeton avec le code de l'appareil jusqu'à ce que l'utilisateur termine l'approbation :

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=<device-code>
&client_id=<your-app>

En cas de succès, cela génère un jeton MCP. Remarque : POST /oauth/token renvoie le corps brut de la RFC 6749/8628 ({ "access_token", "token_type": "Bearer", "scope" }) — il n'utilise pas l'enveloppe standard { ok, data }, donc ne branchez pas sur ok ici. Les portées utilisent le vocabulaire canonique resource:verb (par exemple site:read, preview:create) ; voir Portées et jetons pour le catalogue complet afin que REST et MCP restent synchronisés.

Il n'y a pas de point de terminaison grant_type=refresh_token. Pour renouveler un jeton MCP, faites-le pivoter : POST /admin/mcp-tokens/:tokenId/rotate.

Choisir judicieusement