Krátké odkazy a tajné zprávy přímo z kódu.

1. Ověření

Klíč vytvořte na /app/api-keys (smějí to vlastníci a správci pracovního prostoru). Celý klíč se zobrazí jen jednou; LinkPilot si uchová pouze jeho hash SHA-256. Posílejte ho s každým požadavkem:

Authorization: Bearer lp_live_...

Klíče patří ke konkrétnímu pracovnímu prostoru, takže nikde není parametr tenanta. Zneplatněné, neznámé a chybně formátované klíče i klíče s vypršelou platností vracejí stejnou chybu 401 unauthorized. Klíče se nikdy nezapisují do logů.

Základní URL: https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1

2. Endpointy

Seznamy vracejí { data, next_cursor }; pro další stránku pošlete next_cursor zpět jako cursor. limit je 1 až 100.

3. Příklady

Vytvoření odkazu pomocí 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"]}'

Vytvoření tajné zprávy v JavaScriptu

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)}`;

Výpis odkazů v Pythonu

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"])

Vytvoření anonymního odkazu bez klíče

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"}'

Formální specifikace je zveřejněná tady, ne v repozitáři: dokument OpenAPI 3.1, kolekce pro Postman a psaná referenční dokumentace. Generátor kódu nasměrujte přímo na URL specifikace OpenAPI.

4. Jak se tajné zprávy ukládají

Tady chceme být přesní, protože klient API tu musí odvést skutečnou práci: nešifrovaný payload API vůbec nepřijme.

• Vy šifrujete, my ukládáme blob. Pošlete ciphertext (AES-GCM-256, v1.<iv>.<ct>) s enc_version: 1. Požadavek s polem payload API odmítne, místo aby ho potichu přijalo.
• Klíč musíte připojit sami. Adresa secret_url, kterou vracíme, klíč neobsahuje a obsahovat nemůže: žádný jsme nikdy neviděli. Přidejte #k=<base64url key>. Prohlížeče část za znakem # nikdy neodesílají, takže příjemce dešifruje u sebe.
• Obnova neexistuje. Když klíč ztratíte, tajná zpráva je pryč, pro vás i pro nás. Přesně tak má tahle záruka fungovat.
• Zničení po přečtení, po vypršení platnosti nebo po zneplatnění. Uložený šifrový text se na serveru přepíše.
• API ho nikdy nevrací. Žádný endpoint nevrací obsah ani šifrový text. Číst ho může jen stránka, na které si ho příjemce zobrazí, a ta zobrazení zaznamená.
• Heslové fráze (tarif Pro a vyšší) jsou skutečný druhý faktor: posilují se pomocí PBKDF2-SHA256 a pomocí HKDF se zapracují do klíče, takže samotný odkaz ani samotná heslová fráze obsah nedešifrují. Posílejte jen passphrase_hash, tedy hex SHA-256 heslové fráze normalizované do NFKC. Nikdy neposílejte samotnou heslovou frázi, která je polovinou klíče. Klíč odvozujte ze stejné podoby NFKC, aby tajnou zprávu otevřela i heslová fráze napsaná na jiné klávesnici.
• Co to nepokrývá. Kdo má celý odkaz, má i klíč, takže na krátké platnosti a zničení po přečtení pořád záleží. Přílohy se šifrují stejně, klíčem odvozeným ze stejného odkazu.

Formát přenášených dat popisuje referenční dokumentace API. Pokud ho nechcete implementovat ručně, @uselinkpilot/sdk obstará celou výměnu jedním voláním. Stejný model popisuje stránka bezpečnostní architektura.

5. Limity tarifů a limity požadavků

API uplatňuje stejná pravidla tarifů jako řídicí panel a čte je ze stejného místa, takže i tady platí sdružení pracovních prostorů pod tarifem agentury. GET /me vrací aktuální čísla vašeho pracovního prostoru. Každá ověřená odpověď obsahuje X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset.

Porovnat tarify

6. Veřejné endpointy bez klíče

POST /public/links a POST /public/secrets jsou pro klienty, kteří nemohou zobrazit ověření v prohlížeči: CLI, servery MCP, spouštěč. Přijímají neprůhledné client_id (16 až 64 znaků, generuje se jednou pro každou instalaci) a vytvářejí záznamy ve stejném anonymním fondu jako bezplatné webové nástroje.

• 20 vytvoření na klienta denně a 60 na síť za hodinu, k tomu vlastní limity fondu pro jednotlivé sítě.
• Stejná kontrola podle zdrojů informací o hrozbách, kontrola URL v databázi hrozeb Google a plánované opakované kontroly jako u všech ostatních způsobů vytvoření.
• Bez vlastní domény, bez vlastního slugu, bez heslové fráze; veřejné tajné zprávy se vždy zničí po prvním přečtení a platnost jim vyprší do 24 hodin.
• Odpověď obsahuje claim_token, aby přihlášený uživatel mohl záznam později přiřadit k pracovnímu prostoru. Zacházejte s ním jako s přihlašovacími údaji.

7. Chyby

Každá chyba má tvar { "error": { "code", "message", "upgrade_url"? } }. Chybové zprávy uvádějí název pole, nikdy vaše data. Prostředky v jiných pracovních prostorech vracejí 404, ne 403.