Liens courts et secrets, depuis votre code.

1. Authentification

Créez une clé sur /app/api-keys (propriétaires et administrateurs de l’espace de travail). La clé brute n’est affichée qu’une fois ; LinkPilot n’en conserve que le hash SHA-256. Envoyez-la à chaque requête :

Authorization: Bearer lp_live_...

Chaque clé est liée à un espace de travail, il n’existe donc aucun paramètre de locataire. Les clés révoquées, expirées, inconnues ou mal formées renvoient toutes la même erreur 401 unauthorized. Les clés ne sont jamais écrites dans les journaux.

URL de base : https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1

2. Routes

Les listes renvoient { data, next_cursor } ; renvoyez next_cursor dans cursor pour continuer. limit va de 1 à 100.

3. Exemples

Créer un lien avec curl

curl -X POST "https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1/links" \
  -H "Authorization: Bearer $LINKPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/launch","slug":"launch","tags":["campaign"]}'

Créer un secret en JavaScript

const b64u = (b) => btoa(String.fromCharCode(...new Uint8Array(b)))
  .replace(/+/g, "-").replace(///g, "_").replace(/=+$/, "");

// 1. Encrypt locally. This key is generated here and never sent anywhere.
const key = crypto.getRandomValues(new Uint8Array(32));
const iv = crypto.getRandomValues(new Uint8Array(12));
const k = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
const ct = await crypto.subtle.encrypt(
  { name: "AES-GCM", iv, tagLength: 128 },
  k,
  new TextEncoder().encode("staging db password"),
);
const ciphertext = `v1.${b64u(iv)}.${b64u(ct)}`;

// 2. Store the blob. LinkPilot cannot read it.
const res = await fetch("https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1/secrets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LINKPILOT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ ciphertext, enc_version: 1, ttl_seconds: 3600 }),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const { secret_url } = await res.json();

// 3. Attach the key. Without this the link can never be opened, by anyone.
const shareUrl = `${secret_url}#k=${b64u(key)}`;

Lister les liens en Python

import os, requests

r = requests.get(
    "https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1/links",
    params={"limit": 20},
    headers={"Authorization": f"Bearer {os.environ['LINKPILOT_API_KEY']}"},
)
r.raise_for_status()
for link in r.json()["data"]:
    print(link["short_url"], "->", link["url"])
print("remaining this hour:", r.headers["X-RateLimit-Remaining"])

Créer un lien anonyme sans clé

curl -X POST "https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1/public/links" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","client_id":"my-cli-0123456789abcdef"}'

Le contrat formel est publié ici, pas dans un dépôt : document OpenAPI 3.1, collection Postman et documentation de référence. Pointez directement votre générateur de code vers l’URL OpenAPI.

4. Comment les secrets sont stockés

Nous tenons à être précis, car un client API a ici un vrai travail à faire : l’API refuse purement et simplement un payload en clair.

• Vous chiffrez, nous stockons un blob. Envoyez ciphertext (AES-GCM-256, v1.<iv>.<ct>) avec enc_version: 1. Un envoi de payload est refusé, et non accepté en silence.
• Vous devez ajouter la clé vous-même. Le secret_url que nous renvoyons ne contient pas de clé, et ne peut pas en contenir, car nous n’en avons jamais vu aucune. Ajoutez #k=<base64url key>. Les navigateurs ne transmettent jamais la partie du lien située après le #, donc le destinataire déchiffre en local.
• Aucune récupération possible. Si la clé est perdue, le secret l’est aussi, pour vous comme pour nous. C’est la preuve que la garantie fonctionne.
• Détruit après lecture, à l’expiration ou à la révocation. Le texte chiffré stocké est écrasé côté serveur.
• Jamais renvoyé par l’API. Aucune route ne renvoie un contenu ou un texte chiffré. Seule la page d’affichage du destinataire le lit, et elle enregistre l’ouverture.
• Les phrases de passe (Pro et au-delà) sont un vrai second facteur : renforcées avec PBKDF2-SHA256 puis intégrées à la clé avec HKDF, si bien que ni le lien seul ni la phrase de passe seule ne permettent de déchiffrer. N’envoyez que passphrase_hash, le hash SHA-256 en hexadécimal de la phrase de passe normalisée en NFKC, jamais la phrase de passe brute, qui constitue la moitié de la clé. Dérivez la clé à partir de la même forme NFKC, pour qu’une phrase de passe saisie sur un autre clavier ouvre toujours le secret.
• Ce que cela ne couvre pas. Quiconque détient le lien complet détient la clé, donc une expiration courte et la destruction après lecture restent importantes. Les pièces jointes sont chiffrées de la même manière, avec une clé dérivée du même lien.

Le format d’échange est spécifié dans la référence de l’API, et @uselinkpilot/sdk effectue tout l’échange en un seul appel si vous préférez ne pas l’implémenter vous-même. Le même modèle est décrit sur la page architecture de sécurité.

5. Limites des forfaits et limites de débit

L’API applique les mêmes règles de forfait que le tableau de bord, lues au même endroit, donc le regroupement des forfaits d’agence s’applique ici aussi. GET /me renvoie les valeurs en temps réel pour votre espace de travail. Chaque réponse authentifiée contient les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset.

Comparer les forfaits

6. Routes publiques sans clé

POST /public/links et POST /public/secrets existent pour les clients qui ne peuvent pas afficher de vérification dans un navigateur : les CLI, les serveurs MCP, le lanceur. Elles prennent un client_id opaque (de 16 à 64 caractères, généré une fois par installation) et créent des enregistrements dans le même pool anonyme que les outils web gratuits.

• 20 créations par client et par jour et 60 par réseau et par heure, en plus des plafonds propres au pool pour chaque réseau.
• Le même filtrage par flux de menaces, la même vérification des URL auprès de Google et les mêmes revérifications planifiées que pour toutes les autres voies de création.
• Pas de domaine personnalisé, pas de slug personnalisé, pas de phrase de passe ; les secrets publics sont toujours détruits après une seule lecture et expirent dans les 24 heures.
• La réponse contient un claim_token qui permet à une personne connectée de revendiquer plus tard l’enregistrement, c’est-à-dire de le rattacher à un espace de travail. Traitez-le comme un identifiant de connexion.

7. Erreurs

Chaque erreur a la forme { "error": { "code", "message", "upgrade_url"? } }. Les messages nomment le champ, jamais vos données. Une ressource d’un autre espace de travail renvoie une 404, pas une 403.