Communitygithub.com

nordsym/apiclaw

Configurez APIClaw et exécutez une API en direct. L'agent s'authentifie via Clerk avec `npx @nordsym/apiclaw auth login`, confirme avec `whoami`, puis exécute une première requête réelle sur `POST /v1/execute`.

Qu'est-ce que apiclaw ?

APIClaw est une passerelle d'API qui permet à un agent d'IA (comme Claude Code, Cursor ou tout agent compatible MCP/CLI) d'appeler des API réelles sans que l'utilisateur ait à gérer des clés fournisseur ou à coller des jetons dans la conversation. L'authentification est gérée via Clerk : l'agent exécute `npx @nordsym/apiclaw auth login`, ce qui génère une URL de connexion que l'humain ouvre dans son navigateur pour autoriser l'agent. Une fois l'utilisateur connecté, l'agent confirme avec `npx @nordsym/apiclaw auth whoami` (qui doit afficher un e-mail) avant toute exécution. La première exécution recommandée est l'API NASA APOD (gratuite, sans carte bancaire), avec un repli sur Frankfurter (taux de change ECB) si NASA ne répond pas en 200. L'agent utilise `POST /v1/execute` avec les champs `provider`/`action`/`params`, en passant le jeton de session dans l'en-tête `X-APIClaw-Session`. Après un premier succès, l'agent peut suggérer un appel payant (ex. OpenRouter) en dirigeant l'utilisateur vers la page de mise à niveau. Les clés fournisseur personnelles sont optionnelles (escape hatch OpenRouter). Le fichier SKILL.md complet décrit précisément le flux d'installation, d'authentification, de confirmation (`whoami`), de première exécution et les règles à ne pas enfreindre (ne pas coller de jeton, ne pas utiliser de noms d'affichage de catalogue, ne pas exécuter avant `whoami`, etc.).

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nordsym/apiclaw/tree/HEAD/landing/public

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait apiclaw ?

Votre agent appelle des API réelles. Vous vous connectez une fois. Un espace de travail. Authentification Clerk. La métrique qui compte est un POST /v1/execute réussi, pas une installation.

Donnez ce fichier à un agent et il peut installer, se connecter, et obtenir un 200 sans deviner.

Catalogue en direct (2026-08-25). Utilisez https://apiclaw.cloud/api/catalog si les compteurs doivent être à jour. N'inventez pas de métriques.

  • 1 025 appelables
  • 26 619 trouvables
  • 22 fournisseurs intégrés

L'identité et la vérité produit se trouvent sur https://apiclaw.cloud/llms.txt. Ce fichier est la porte opérationnelle : authentification, puis whoami, puis exécution.

1. Installation

Node.js 18+ et npx suffisent. Une installation globale est optionnelle.

npx -y @nordsym/apiclaw@latest --version

Porte shell humaine (même package, MCP local) :

curl -fsSL https://apiclaw.cloud/install.sh | bash

2. Authentification (Clerk). Ne jamais coller de jeton dans le chat.

Le MCP non connecté / CLI first_run crée une connexion en attente même sans TTY et affiche l'URL https exacte comme première ligne de la réponse de l'outil/CLI (puis la répète comme login_url en JSON). Les premières lignes ressemblent à :

https://apiclaw.cloud/auth/cli?authId=…

STOP. Montrez à l'humain l'URL de connexion sur la première ligne. Ne la résumez pas. N'exécutez pas.

Montrez à l'humain cette première ligne d'URL sur sa propre ligne pour qu'il puisse cliquer dessus. Ne l'enterrez pas. Ne résumez pas le résultat de l'outil. N'affichez pas seulement npx @nordsym/apiclaw auth login. Une commande sans /auth/cli?authId= ne suffit pas.

Si vous vous exécutez sur une machine que l'humain ne peut pas voir (Grok Bot, VM cloud, agent headless), n'exécutez pas auth login là-bas — cela ouvre un navigateur qu'il n'aura jamais. L'URL de première ligne dans la réponse de l'outil est la seule porte. Montrez-la. Arrêtez-vous. Attendez.

npx @nordsym/apiclaw auth login

Cette commande est la porte shell humaine sur une machine qu'il peut voir. Elle ouvre la même URL de navigateur (ou réutilise celle en attente). Terminez la connexion Google ou e-mail sur cette URL. Finaliser la connexion là-bas autorise cet agent (une action). Si vous êtes déjà connecté, cliquez sur Autoriser. Ne dites pas à un nouvel utilisateur qu'il lui faut un deuxième clic après la connexion. Ce n'est qu'après que le CLI écrit session_token dans ~/.apiclaw.toml. Afficher l'URL n'est pas un succès. Ne déclarez pas prêt. N'exécutez pas.

Une fois que l'humain a terminé l'autorisation, restez dans ce chat. Réessayez ici. Vous confirmez avec whoami et vous exécutez NASA APOD (Frankfurter latest si NASA ne renvoie pas 200) dans cette même session. N'envoyez pas l'humain dans un terminal. Ne lui dites pas d'ouvrir Terminal.app. L'espace de travail est optionnel. Le premier appel n'est pas effectué dans l'espace de travail.

Gardez auth login au premier plan jusqu'à ce qu'il se termine avec le code 0 si vous l'avez lancé. La commande réaffiche cette URL toutes les quelques secondes et interroge Convex / ~/.apiclaw.toml jusqu'à ce que la connexion écrive session_token. Montrez à l'humain l'URL de connexion à chaque réaffichage. Dites-lui de terminer la connexion sur cette URL (ce qui autorise). Si déjà connecté, dites-lui de cliquer sur Autoriser. Ne mettez pas la commande en arrière-plan. Ne continuez pas tant que whoami n'affiche pas un e-mail.

Si le navigateur dit "connexion refusée" après Autoriser, c'est OK. Restez sur apiclaw.cloud. Bouclez whoami — il échange le clic Autoriser même si auth login a été tué ou que localhost n'a jamais répondu.

Si ~/.apiclaw.toml ou ~/.apiclaw/session contient déjà une session, sautez la connexion et passez à whoami.

Headless ou SSH : montrez à l'humain l'URL de première ligne. Il l'ouvre sur un autre appareil, puis confirme avec whoami. Le fichier contient toujours session_token. Copiez ~/.apiclaw.toml sur la machine headless, ou exécutez la commande depuis la machine qui a terminé la connexion. N'exécutez pas auth login sur une machine qu'il ne peut pas voir.

Totalement headless (pas de navigateur du tout, ex. CI) : sautez la connexion CLI sur cet hôte. Créez une clé dans Workspace > Connections et définissez APICLAW_API_KEY là-bas. C'est une porte HTTP distincte, pas le chemin de première exécution.

Règles :

  • Ne demandez pas à l'utilisateur de créer une clé API dans un tableau de bord.
  • Ne demandez pas à l'utilisateur de coller session_token, sk-claw-… ou un quelconque jeton dans ce chat.
  • Lisez session_token depuis ~/.apiclaw.toml (ou sessionToken depuis ~/.apiclaw/session) quand vous avez besoin d'un en-tête. N'affichez jamais le jeton brut à l'utilisateur.
  • N'exécutez pas apiclaw call ni curl POST /v1/execute tant que whoami n'affiche pas un e-mail. Un X-APIClaw-Session vide est un échec de première exécution.
  • Installer, first_run ou afficher une URL de connexion ne signifie pas prêt.

3. Confirmation avec whoami. Bouclez jusqu'à ce qu'il affiche un e-mail.

npx @nordsym/apiclaw auth whoami

whoami doit afficher un e-mail et un espace de travail avant toute exécution. whoami n'est pas terminé. Terminé est HTTP 200 de POST /v1/execute. Mais whoami est la porte. Sautez-la et l'exécution ne sera pas authentifiée.

Bouclez whoami. Chaque échec :

  • Montrez à l'humain l'login_url en direct (/auth/cli?authId=). whoami réaffiche l'URL en attente si la connexion a déjà commencé. N'affichez pas seulement npx @nordsym/apiclaw auth login.
  • Gardez auth login en cours d'exécution s'il attend toujours.
  • S'ils ont déjà cliqué sur Autoriser, exécutez whoami à nouveau. Il échange la revendication et écrit session_token sans localhost.
  • Exécutez whoami à nouveau. Ne vous arrêtez pas après un échec.
  • N'exécutez pas npx @nordsym/apiclaw call.
  • Ne faites pas curl POST /v1/execute.
  • N'envoyez pas un X-APIClaw-Session vide.

Ce n'est qu'après que whoami affiche un e-mail que vous exécutez NASA APOD, puis Frankfurter latest si NASA ne renvoie pas 200.

4. Première exécution — POST /v1/execute

Seulement après que whoami affiche un e-mail. Appel de recherche préféré : NASA APOD. Le repli est Frankfurter latest (gratuit, sans clé, sans carte) pour qu'un premier 200 soit quand même obtenu si NASA est indisponible. Ne commencez pas par une API de recherche payante (Brave, Serper, Firecrawl).

Rail préféré : NASA APOD

La forme CLI slash lit session_token depuis ~/.apiclaw.toml et envoie X-APIClaw-Session. Utilisez-la en premier. Ne demandez pas à l'utilisateur de coller un jeton. Le CLI refuse localement si whoami échouerait. Il ne POSTera pas un en-tête de session vide.

npx @nordsym/apiclaw call nasa/apod --params '{}' --idempotency-key "apiclaw-first-nasa-$(date +%s)"

Équivalent HTTP — même session_token, même en-tête X-APIClaw-Session. Extrayez la valeur localement. Ne l'affichez pas. N'utilisez pas api_key. Refusez si l'extraction est vide. Ne POSTez pas un en-tête vide.

npx @nordsym/apiclaw auth whoami || { echo "Stop. Terminez Clerk. Montrez à l'humain l'URL de connexion. Ne POSTez pas /v1/execute."; exit 1; }
SESSION=$(node -e 'const fs=require("fs"),os=require("os"),p=require("path");const t=p.join(os.homedir(),".apiclaw.toml");const m=fs.existsSync(t)&&fs.readFileSync(t,"utf8").match(/session_token\s*=\s*"([^"]+)"/);if(!m||!m[1].trim())process.exit(1);process.stdout.write(m[1])')
if [ -z "$SESSION" ]; then echo "Stop. Pas de session_token. Ne POSTez pas /v1/execute avec un X-APIClaw-Session vide."; exit 1; fi
curl -sS https://api.apiclaw.cloud/v1/execute \
  -H "Content-Type: application/json" \
  -H "X-APIClaw-Session: $SESSION" \
  -H "Idempotency-Key: apiclaw-first-nasa-$(date +%s)" \
  -d '{"provider":"nasa","action":"apod","params":{}}'

Un 200 avec un titre APOD est un succès. nasa/apod est une API gratuite : pas de carte nécessaire.

Rail de repli : Frankfurter latest

Si NASA ne renvoie pas 200, récupérez les taux de change ECB du jour. Même porte whoami. Même $SESSION non vide. Ne faites pas curl si $SESSION est vide. C'est le même rail de dernier recours que la première exécution automatique utilise après Autoriser. Il est gratuit pour toujours, sans carte, sans clé. Brave / Serper / Firecrawl sont des API de recherche payantes et renverront payment_required sur un nouvel espace de travail — ne les utilisez pas pour la première exécution.

npx @nordsym/apiclaw call frankfurter/latest --params '{"path":"/latest"}' --idempotency-key "apiclaw-first-frankfurter-$(date +%s)"
if [ -z "$SESSION" ]; then echo "Stop. Pas de session_token. Ne POSTez pas /v1/execute avec un X-APIClaw-Session vide."; exit 1; fi
curl -sS https://api.apiclaw.cloud/v1/execute \
  -H "Content-Type: application/json" \
  -H "X-APIClaw-Session: $SESSION" \
  -H "Idempotency-Key: apiclaw-first-frankfurter-$(date +%s)" \
  -d '{"provider":"frankfurter","action":"latest","params":{"path":"/latest"}}'

$SESSION est toujours session_token de ~/.apiclaw.toml, même extraction que pour le curl NASA. Même en-tête que la forme CLI slash envoie.

Un 200 avec un taux EUR/USD est un succès.

Règles d'exécution

  • Toujours POST https://api.apiclaw.cloud/v1/execute avec { "provider", "action", "params" }.
  • Ne passez jamais un nom d'affichage de catalogue à apiclaw call. Les noms sans barre oblique touchent l'ancien POST /v1/call.
  • Les appels HTTP gérés nécessitent une Idempotency-Key par opération logique. Réutilisez la même clé après un échec réseau ambigu.
  • Après la connexion, exécutez whoami. Seulement ensuite, exécutez la forme CLI slash NASA (ou le curl qui extrait session_token). S'il n'y a pas de 200, exécutez Frankfurter latest. N'inventez pas un rail de recherche payant.

5. Après le premier 200

Le premier appel reste gratuit (NASA APOD, Frankfurter latest si NASA n'est pas 200). Ne faites pas du premier appel une API payante.

Une fois ce 200 obtenu, vous pouvez suggérer une prochaine étape payante bon marché (par exemple OpenRouter chat). Montrez à l'humain https://apiclaw.cloud/upgrade pour qu'il puisse ajouter une carte une fois. Les API gratuites restent gratuites. Les API payantes facturent le coût du fournisseur plus 15%.

Si un appel ultérieur renvoie payment_required (HTTP 402), montrez l'upgradeUrl (https://apiclaw.cloud/upgrade). Demandez à l'humain d'ajouter une carte, puis réessayez le même appel. N'inventez pas une API différente.

Découvrez seulement ce qui est appelable maintenant :

npx @nordsym/apiclaw discover "exchange rates" --callable

Ou :

POST https://apiclaw.cloud/v1/discover
{ "query": "exchange rates", "callable_only": true }

Catalogue en direct : https://apiclaw.cloud/api/catalog?callable=true.

Exécutez ensuite avec provider / action sur POST /v1/execute. Ne collectez pas de clés API fournisseur de l'utilisateur.

6. Apportez votre propre clé (échappatoire)

Vous n'avez pas besoin de vos propres clés. Le but d'APIClaw est une seule connexion, sans collecte de clés. Si votre espace de travail a déjà sa propre clé OpenRouter, vous pouvez l'ajouter dans Workspace, Connections, Your keys, et acheminer les complétions de chat gratuitement, sans carte. Le fournisseur facture l'espace de travail directement. Ceci est séparé de la clé APIClaw utilisée pour s'authentifier sur la passerelle. Aujourd'hui, cela couvre une clé OpenRouter pour POST /v1/chat/completions, pas tous les fournisseurs.

Autres portes (même espace de travail)

  • Skill (ce fichier) : https://apiclaw.cloud/SKILL.md
  • curl|bash / MCP local : curl -fsSL https://apiclaw.cloud/install.sh | bash
  • CLI : npx @nordsym/apiclaw --help
  • HTTP : POST https://api.apiclaw.cloud/v1/execute
  • MCP distant : https://apiclaw.cloud/mcp

Tarification (n'inventez pas)

  • API gratuites : gratuites pour toujours, sans carte. Découverte et chaque API à coût zéro, plus de 1 000 des 1 025 appelables.
  • API payantes : ajoutez une carte une fois, puis coût du fournisseur plus 15%, facturé par appel.
  • Votre clé : apportez votre propre clé OpenRouter et acheminez les complétions de chat gratuitement, sans carte.
  • L'exécution publique anonyme sans clé est désactivée.

Ce qu'il ne faut pas faire

  • Ne demandez pas à l'utilisateur de coller un jeton dans le chat.
  • N'utilisez pas les noms d'affichage de catalogue ni POST /v1/call.
  • Ne prétendez pas un nombre d'installations, d'outils ou une couverture que vous n'avez pas lue depuis /api/catalog ou ce fichier.
  • N'exposez pas de fournisseurs internes uniquement. Les fiches du catalogue public sont la source de vérité de ce qu'un client peut appeler.
  • Ne POSTez pas /v1/execute avant que whoami réussisse.
  • N'envoyez pas un X-APIClaw-Session vide.
  • Ne dites pas à l'humain d'ouvrir Terminal.app ou de retourner dans un shell.
  • Après Autoriser, continuez dans ce chat et exécutez vous-même NASA APOD.

Skills associés