קישורים מקוצרים וסודות, ישירות מהקוד

1. אימות

צרו מפתח בכתובת /app/api-keys (לבעלים ולמנהלים של סביבת העבודה). המפתח עצמו מוצג פעם אחת בלבד, ו-LinkPilot שומר רק את ה-hash שלו ב-SHA-256. שלחו אותו בכל בקשה:

Authorization: Bearer lp_live_...

כל מפתח קשור לסביבת עבודה אחת, ולכן אין בשום מקום פרמטר tenant. מפתח שבוטל, שפג תוקפו, שאינו מוכר או שאינו תקין מחזיר תמיד את אותה תגובה, 401 unauthorized. מפתחות אף פעם לא נכתבים ליומנים.

כתובת בסיס: 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, ה-hex של SHA-256 על ביטוי הסיסמה אחרי נרמול 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 תווים, נוצר פעם אחת לכל התקנה) ויוצרים רשומות באותו מאגר אנונימי שבו משתמשים הכלים החינמיים באתר.

• 20 יצירות ללקוח ביום ו-60 לרשת בשעה, וגם המגבלות של המאגר עצמו לכל רשת.
• אותו סינון מול מקורות מידע על איומים, אותה בדיקת URL מול Google ואותן בדיקות חוזרות מתוזמנות כמו בכל דרך יצירה אחרת.
• בלי דומיין מותאם, בלי סיומת מותאמת אישית ובלי ביטוי סיסמה. סודות ציבוריים תמיד נמחקים אחרי קריאה אחת, ותוקפם פג תוך 24 שעות.
• התגובה כוללת claim_token, כדי שמשתמש מחובר יוכל לשייך את הרשומה לסביבת עבודה מאוחר יותר. התייחסו אליו כמו לפרטי התחברות.

7. שגיאות

כל שגיאה היא { "error": { "code", "message", "upgrade_url"? } }. ההודעות מציינות את השדה, אף פעם לא את הנתונים שלכם. משאב בסביבת עבודה אחרת מחזיר 404, לא 403.