शॉर्ट लिंक और सीक्रेट, सीधे कोड से

1. ऑथेंटिकेशन

/app/api-keys पर key बनाएं (वर्कस्पेस के ओनर और एडमिन)। असली key सिर्फ़ एक बार दिखती है; LinkPilot सिर्फ़ उसका SHA-256 हैश रखता है। इसे हर रिक्वेस्ट के साथ भेजें:

Authorization: Bearer lp_live_...

API keys एक वर्कस्पेस से जुड़ी होती हैं, इसलिए कहीं भी tenant पैरामीटर नहीं है। वापस ली गई, एक्सपायर हो चुकी, अनजान और गलत फ़ॉर्मैट वाली, सभी keys एक ही 401 unauthorized लौटाती हैं। API keys कभी लॉग में नहीं लिखी जातीं।

बेस 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"])

बिना key के गुमनाम लिंक बनाएं

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 कलेक्शन और लिखित रेफ़रेंस। अपने कोड जनरेटर को सीधे OpenAPI URL पर लगाएं।

4. सीक्रेट कैसे स्टोर होते हैं

हम यहां बिल्कुल सटीक रहना चाहते हैं, क्योंकि API क्लाइंट को यहां असली काम करना होता है: API बिना एन्क्रिप्शन वाला payload बिल्कुल स्वीकार नहीं करता।

• एन्क्रिप्ट आप करते हैं, हम सिर्फ़ ब्लॉब स्टोर करते हैं। ciphertext (AES-GCM-256, v1.<iv>.<ct>) को enc_version: 1 के साथ भेजें। payload भेजने पर रिक्वेस्ट चुपचाप मान लेने की जगह ठुकरा दी जाती है।
• कुंजी आपको खुद जोड़नी होगी। हम जो secret_url लौटाते हैं उसमें कुंजी नहीं होती और हो भी नहीं सकती: हमने उसे कभी देखा ही नहीं। #k=<base64url key> जोड़ें। ब्राउज़र # के बाद का हिस्सा कभी नहीं भेजते, इसलिए प्राप्तकर्ता अपने डिवाइस पर ही डिक्रिप्ट करता है।
• वापस पाने का कोई तरीका नहीं है। कुंजी खो गई तो सीक्रेट हमेशा के लिए गया, आपके लिए भी और हमारे लिए भी। गारंटी इसी तरह काम करती है।
• पढ़े जाने, एक्सपायर होने या वापस लिए जाने पर मिट जाता है। स्टोर किया हुआ सिफ़रटेक्स्ट सर्वर पर ओवरराइट कर दिया जाता है।
• API इसे कभी नहीं लौटाता। कोई भी रूट कॉन्टेंट या सिफ़रटेक्स्ट वापस नहीं भेजता। इसे सिर्फ़ प्राप्तकर्ता का सीक्रेट खोलने वाला पेज पढ़ता है, और सीक्रेट के खुलने को भी वही दर्ज करता है।
• पासफ़्रेज़ (Pro और उससे ऊपर) असली दूसरा फ़ैक्टर हैं: इन्हें PBKDF2-SHA256 से स्ट्रेच करके HKDF से कुंजी में मिला दिया जाता है, इसलिए न अकेला लिंक डिक्रिप्ट कर सकता है, न अकेला पासफ़्रेज़। सिर्फ़ passphrase_hash भेजें, यानी NFKC में नॉर्मलाइज़ किए गए पासफ़्रेज़ का SHA-256 hex। असली पासफ़्रेज़ कभी न भेजें, क्योंकि वह कुंजी का आधा हिस्सा है। कुंजी भी इसी NFKC रूप से निकालें, ताकि किसी दूसरे कीबोर्ड पर टाइप किया गया पासफ़्रेज़ भी सीक्रेट खोल सके।
• यह किससे नहीं बचाता। जिसके पास पूरा लिंक है, उसके पास कुंजी भी है, इसलिए छोटी एक्सपायरी और पढ़ते ही मिटना अब भी ज़रूरी हैं। फ़ाइल अटैचमेंट भी इसी तरह एन्क्रिप्ट होते हैं, उसी लिंक से निकली कुंजी से।

वायर फ़ॉर्मैट API रेफ़रेंस में दिया गया है। अगर आप इसे खुद नहीं लिखना चाहते, तो @uselinkpilot/sdk पूरा लेन-देन एक कॉल में कर देता है। यही मॉडल सिक्योरिटी आर्किटेक्चर पेज पर भी समझाया गया है।

5. प्लान की सीमाएं और रेट लिमिट

API डैशबोर्ड वाले ही प्लान नियम लागू करता है, उसी जगह से पढ़कर, इसलिए एजेंसी के तहत मिलने वाली सीमाएं यहां भी लागू होती हैं। GET /me आपके वर्कस्पेस के मौजूदा आंकड़े लौटाता है। ऑथेंटिकेशन वाले हर रिस्पॉन्स में X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset होते हैं।

प्लान की तुलना करें

6. बिना key के पब्लिक रूट

POST /public/links और POST /public/secrets उन क्लाइंट के लिए हैं जो ब्राउज़र चैलेंज नहीं दिखा सकते: CLI, MCP सर्वर, लॉन्चर। ये एक ओपेक client_id लेते हैं (16 से 64 कैरेक्टर, हर इंस्टॉल पर एक बार बनाया गया) और वही गुमनाम पूल इस्तेमाल करते हैं जिसमें मुफ़्त वेब टूल के रिकॉर्ड बनते हैं।

• हर क्लाइंट से हर दिन 20 और हर नेटवर्क से हर घंटे 60 रिकॉर्ड, और इसके ऊपर पूल की अपनी प्रति-नेटवर्क सीमाएं।
• बाकी हर तरीके की तरह यहां भी थ्रेट फ़ीड से जांच, Google URL थ्रेट लुकअप और तय समय पर दोबारा जांच होती है।
• कस्टम डोमेन, कस्टम स्लग और पासफ़्रेज़ नहीं मिलते; पब्लिक सीक्रेट हमेशा एक बार पढ़े जाने के बाद मिट जाते हैं और 24 घंटे के अंदर एक्सपायर हो जाते हैं।
• रिस्पॉन्स में एक claim_token होता है, जिससे साइन इन किया हुआ यूज़र बाद में रिकॉर्ड को क्लेम करके अपने वर्कस्पेस से जोड़ सकता है। इसे क्रेडेंशियल की तरह संभालें।

7. एरर

हर एरर { "error": { "code", "message", "upgrade_url"? } } होता है। मैसेज में फ़ील्ड का नाम होता है, आपका डेटा कभी नहीं। दूसरे वर्कस्पेस के रिसोर्स पर 404 मिलता है, 403 नहीं।