Σύντομοι σύνδεσμοι και μυστικά, από κώδικα.

1. Έλεγχος ταυτότητας

Δημιουργήστε ένα κλειδί στο /app/api-keys (κάτοχοι και διαχειριστές του χώρου εργασίας). Το πλήρες κλειδί εμφανίζεται μία φορά. Το LinkPilot κρατά μόνο το SHA-256 hash του. Στείλτε το σε κάθε αίτημα:

Authorization: Bearer lp_live_...

Τα κλειδιά ανήκουν σε έναν χώρο εργασίας, οπότε δεν υπάρχει πουθενά παράμετρος tenant. Κλειδιά που έχουν ανακληθεί, έχουν λήξει, είναι άγνωστα ή λανθασμένα επιστρέφουν όλα το ίδιο 401 unauthorized. Τα κλειδιά δεν καταγράφονται ποτέ σε logs.

Βασικό URL: https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1

2. Διαδρομές

Οι λίστες επιστρέφουν { data, next_cursor }. Για να συνεχίσετε, στείλτε το next_cursor πίσω ως cursor. Το limit είναι από 1 έως 100.

3. Παραδείγματα

Δημιουργία συνδέσμου με 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"]}'

Δημιουργία μυστικού από 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)}`;

Λίστα συνδέσμων από 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"])

Δημιουργία ανώνυμου συνδέσμου χωρίς κλειδί

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

Η επίσημη προδιαγραφή δημοσιεύεται εδώ, όχι σε αποθετήριο: έγγραφο OpenAPI 3.1, συλλογή Postman και η γραπτή τεκμηρίωση. Δώστε στη γεννήτρια κώδικα απευθείας το URL του OpenAPI.

4. Πώς αποθηκεύονται τα μυστικά

Θέλουμε να είμαστε ακριβείς, γιατί εδώ ο πελάτης του API έχει πραγματική δουλειά: το API δεν δέχεται καθόλου μη κρυπτογραφημένο payload.

• Εσείς κρυπτογραφείτε, εμείς αποθηκεύουμε ένα blob. Στείλτε ciphertext (AES-GCM-256, v1.<iv>.<ct>) με enc_version: 1. Αν στείλετε payload, απορρίπτεται, δεν γίνεται σιωπηλά δεκτό.
• Το κλειδί το προσθέτετε εσείς. Το secret_url που επιστρέφουμε δεν περιέχει κλειδί και δεν θα μπορούσε: δεν έχουμε δει ποτέ κανένα. Προσθέστε #k=<base64url key>. Τα προγράμματα περιήγησης δεν στέλνουν ποτέ το τμήμα μετά το #, οπότε ο παραλήπτης αποκρυπτογραφεί τοπικά.
• Δεν υπάρχει ανάκτηση. Αν χάσετε το κλειδί, το μυστικό χάνεται, για εσάς και για εμάς. Έτσι λειτουργεί η εγγύηση.
• Καταστρέφεται μετά την ανάγνωση, τη λήξη ή την ανάκληση. Το αποθηκευμένο κρυπτογράφημα αντικαθίσταται στον διακομιστή.
• Το API δεν το επιστρέφει ποτέ. Καμία διαδρομή δεν επιστρέφει περιεχόμενο ή κρυπτογράφημα. Το διαβάζει μόνο η σελίδα εμφάνισης του παραλήπτη, η οποία καταγράφει την προβολή.
• Οι φράσεις πρόσβασης (Pro και πάνω) είναι πραγματικός δεύτερος παράγοντας: ενισχύονται με PBKDF2-SHA256 και ενσωματώνονται στο κλειδί με HKDF, οπότε ούτε ο σύνδεσμος μόνος ούτε η φράση πρόσβασης μόνη αποκρυπτογραφεί. Στείλτε μόνο το passphrase_hash, δηλαδή το SHA-256 σε hex της φράσης πρόσβασης κανονικοποιημένης κατά NFKC, και ποτέ την ίδια τη φράση, που είναι το μισό κλειδί. Παράγετε το κλειδί από την ίδια μορφή NFKC, ώστε η φράση να ανοίγει το μυστικό ακόμη κι αν πληκτρολογηθεί σε άλλο πληκτρολόγιο.
• Τι δεν καλύπτει. Όποιος έχει ολόκληρο τον σύνδεσμο έχει και το κλειδί, οπότε η σύντομη λήξη και η διαγραφή μετά την ανάγνωση εξακολουθούν να μετράνε. Τα συνημμένα αρχεία κρυπτογραφούνται με τον ίδιο τρόπο, με κλειδί που παράγεται από τον ίδιο σύνδεσμο.

Η μορφή μετάδοσης περιγράφεται στην τεκμηρίωση του API, και το @uselinkpilot/sdk κάνει όλη την ανταλλαγή με μία κλήση, αν δεν θέλετε να την υλοποιήσετε μόνοι σας. Το ίδιο μοντέλο περιγράφεται στη σελίδα αρχιτεκτονικής ασφάλειας.

5. Όρια πακέτων και όρια αιτημάτων

Το API εφαρμόζει τους ίδιους κανόνες πακέτου με τον πίνακα ελέγχου, από την ίδια πηγή, οπότε και η συγκεντρωτική κάλυψη ενός πακέτου Agency ισχύει κι εδώ. Το GET /me επιστρέφει τις τρέχουσες τιμές για τον χώρο εργασίας σας. Κάθε απάντηση σε αίτημα με έλεγχο ταυτότητας περιέχει X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset.

Σύγκριση πακέτων

6. Δημόσιες διαδρομές χωρίς κλειδί

Τα POST /public/links και POST /public/secrets υπάρχουν για πελάτες που δεν μπορούν να εμφανίσουν έλεγχο στο πρόγραμμα περιήγησης: CLI, διακομιστές MCP, τον launcher. Δέχονται ένα αδιαφανές client_id (16 έως 64 χαρακτήρες, δημιουργείται μία φορά ανά εγκατάσταση) και δημιουργούν εγγραφές στην ίδια ανώνυμη δεξαμενή με τα δωρεάν εργαλεία web.

• 20 δημιουργίες ανά πελάτη την ημέρα και 60 ανά δίκτυο την ώρα, συν τα όρια ανά δίκτυο της ίδιας της δεξαμενής.
• Ο ίδιος έλεγχος σε λίστες απειλών, ο ίδιος έλεγχος URL στη Google και οι ίδιοι προγραμματισμένοι επανέλεγχοι με κάθε άλλο τρόπο δημιουργίας.
• Χωρίς δικό σας domain, χωρίς προσαρμοσμένη κατάληξη συνδέσμου, χωρίς φράση πρόσβασης. Τα δημόσια μυστικά διαγράφονται πάντα μετά από μία ανάγνωση και λήγουν μέσα σε 24 ώρες.
• Η απάντηση περιέχει ένα claim_token, ώστε ένας συνδεδεμένος χρήστης να προσθέσει αργότερα την εγγραφή σε χώρο εργασίας. Χειριστείτε το ως διαπιστευτήριο.

7. Σφάλματα

Κάθε σφάλμα έχει τη μορφή { "error": { "code", "message", "upgrade_url"? } }. Τα μηνύματα αναφέρουν το πεδίο, ποτέ τα δεδομένα σας. Πόροι σε άλλους χώρους εργασίας επιστρέφουν 404, όχι 403.