Lyhytlinkit ja salaisuudet suoraan koodista

1. Tunnistautuminen

Luo avain sivulla /app/api-keys (työtilan omistajat ja ylläpitäjät). Avain näytetään kokonaisena vain kerran, ja LinkPilot säilyttää siitä vain SHA-256-tiivisteen. Lähetä avain jokaisen pyynnön mukana:

Authorization: Bearer lp_live_...

Avaimet on sidottu työtilaan, joten tenant-parametria ei ole missään. Mitätöidystä, vanhentuneesta, tuntemattomasta ja väärämuotoisesta avaimesta palautuu sama vastaus 401 unauthorized. Avaimia ei koskaan kirjoiteta lokeihin.

Perusosoite: https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1

2. Reitit

Listat palauttavat muodon { data, next_cursor }. Jatka antamalla next_cursor takaisin parametrina cursor. Parametrin limit arvo on 1–100.

3. Esimerkit

Luo linkki curlilla

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

Luo salaisuus JavaScriptillä

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

Listaa linkit Pythonilla

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

Luo nimetön linkki ilman avainta

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

Rajapinnan virallinen kuvaus julkaistaan täällä eikä koodivarastossa: OpenAPI 3.1 -dokumentti, Postman-kokoelma ja kirjallinen viiteopas. Osoita koodigeneraattorisi suoraan OpenAPI-kuvauksen URL-osoitteeseen.

4. Miten salaisuudet tallennetaan

Haluamme olla tarkkoja, koska API-asiakasohjelman on tässä tehtävä oikeaa työtä: API ei hyväksy selväkielistä kenttää payload lainkaan.

• Sinä salaat, me tallennamme salatun tavujonon. Lähetä kenttä ciphertext (AES-GCM-256, v1.<iv>.<ct>) ja sen mukana enc_version: 1. Jos lähetät kentän payload, pyyntö hylätään eikä sitä hyväksytä hiljaa.
• Avain on lisättävä itse. Palauttamamme secret_url ei sisällä avainta eikä voisikaan: emme ole koskaan nähneet sitä. Lisää loppuun #k=<base64url key>. Selaimet eivät koskaan lähetä merkin # jälkeistä osaa, joten vastaanottaja purkaa salauksen omalla laitteellaan.
• Palautusta ei ole. Jos avain katoaa, salaisuus on menetetty sekä sinulta että meiltä. Juuri tämä osoittaa, että takuu toimii.
• Tuhotaan, kun salaisuus avataan, vanhenee tai mitätöidään. Tallennettu salateksti ylikirjoitetaan palvelimella.
• API ei koskaan palauta sitä. Mikään reitti ei palauta sisältöä eikä salatekstiä. Sen lukee vain vastaanottajan avaussivu, joka kirjaa avauksen.
• Salalauseet (Pro-paketista ylöspäin) ovat todellinen toinen tekijä: ne venytetään PBKDF2-SHA256:lla ja yhdistetään avaimeen HKDF:llä, joten salausta ei voi purkaa pelkällä linkillä eikä pelkällä salalauseella. Lähetä vain passphrase_hash eli NFKC-normalisoidun salalauseen SHA-256-tiiviste heksamuodossa. Älä koskaan lähetä salalausetta sellaisenaan, koska se on puolet avaimesta. Johda avain samasta NFKC-muodosta, jotta salaisuus aukeaa myös toisella näppäimistöllä kirjoitetulla salalauseella.
• Mitä tämä ei kata. Koko linkin haltijalla on myös avain, joten lyhyt voimassaoloaika ja tuhoutuminen lukemisen jälkeen ovat edelleen tärkeitä. Liitetiedostot salataan samalla tavalla avaimella, joka johdetaan samasta linkistä.

Siirtomuoto on kuvattu API-viitteessä, ja kirjasto @uselinkpilot/sdk hoitaa koko vaihdon yhdellä kutsulla, jos et halua toteuttaa sitä itse. Samaa mallia kuvataan tietoturva-arkkitehtuurisivulla.

5. Pakettien rajat ja pyyntörajat

API noudattaa samoja pakettisääntöjä kuin hallintapaneeli ja lukee ne samasta paikasta, joten myös toimiston asiakastyötilojen yhteenlasketut rajat pätevät tässä. Kutsu GET /me palauttaa työtilasi ajantasaiset luvut. Jokaisessa tunnistautuneen pyynnön vastauksessa on otsakkeet X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset.

Vertaa paketteja

6. Julkiset reitit ilman avainta

Reitit POST /public/links ja POST /public/secrets ovat asiakasohjelmille, jotka eivät pysty näyttämään selaimessa tehtävää tarkistusta: CLI-työkaluille, MCP-palvelimille ja käynnistimelle. Ne ottavat vastaan läpinäkymättömän tunnisteen client_id (16–64 merkkiä, luodaan kerran asennusta kohden) ja luovat tietueita samaan nimettömään varantoon kuin ilmaiset verkkotyökalut.

• 20 luontia asiakasohjelmaa kohden päivässä ja 60 verkkoa kohden tunnissa, minkä lisäksi varannolla on omat verkkokohtaiset rajansa.
• Sama uhkasyötteiden seulonta, Googlen URL-uhkatarkistus ja ajastetut uusintatarkistukset kuin kaikilla muillakin luontitavoilla.
• Ei omaa verkkotunnusta, omaa polkutunnusta eikä salalausetta. Julkiset salaisuudet tuhoutuvat aina yhden lukemisen jälkeen ja vanhenevat 24 tunnin kuluessa.
• Vastauksessa on liittämistunniste claim_token, jolla kirjautunut käyttäjä voi myöhemmin liittää tietueen työtilaan. Käsittele sitä kuin kirjautumistietoja.

7. Virheet

Jokainen virhe on muotoa { "error": { "code", "message", "upgrade_url"? } }. Viestit nimeävät kentän, eivät koskaan tietojasi. Muiden työtilojen resursseista palautuu 404 eikä 403.