API कुंजियाँ

GET /keys हर वह कुंजी सूचीबद्ध करता है जिसे कॉल करने वाला देख सकता है, सबसे नई पहले और एक बार में एक पेज, उसकी स्थिति, स्कोप, भूमिका, भेजने के दायरे, पिछले इस्तेमाल और यह कि किसने उसे बनाया और आख़िरी बार बदला, सबके साथ। GET /keys/{id} एक पढ़ता है। कोई भी रीड कभी सीक्रेट नहीं लौटाता: दो कुंजियों में फ़र्क करने के लिए maskedKey काफ़ी है। दोनों को keys:read चाहिए।

{  "object": "api_key",  "id": "4c1b257a66287fd113bd89d0",  "name": "Billing sender",  "maskedKey": "oe_live_4c1b…kX7a",  "status": "active",  "scopes": ["emails:send"],  "roleId": null,  "domainAllowlist": ["billing.acme.com"],  "expiresAt": "2026-12-22T09:00:00.000Z",  "lastUsedAt": "2026-09-23T08:14:02.000Z",  "createdBy": { "kind": "apiKey", "name": "API key Provisioner", "label": "API key Provisioner" }}

• —POST /keys एक कुंजी बनाता है और उसका सीक्रेट token में एक बार लौटाता है। न दिए जाने पर स्कोप emails:send होता है और भूमिका, भेजने का दायरा और समाप्ति कॉल करने वाले की अपनी होती हैं।
• —PATCH /keys/{id} कुंजी का नाम बदलता है, उसके स्कोप या भेजने का दायरा बदल देता है, और enabled से उसे बंद और चालू करता है। बंद करना उलटा जा सकने वाला विकल्प है: कुंजी सब कुछ रखती है और फिर से चालू होने तक inactive_api_key के साथ ठुकराई जाती है।
• —POST /keys/{id}/rotate कुंजी को नया सीक्रेट देता है और उसे एक बार लौटाता है। पुराना सीक्रेट उसी पल काम करना बंद कर देता है जब कॉल लौटती है।
• —POST /keys/{id}/revoke कुंजी को हमेशा के लिए सेवा से हटा देता है, वैकल्पिक reason के साथ। इसके बाद DELETE /keys/{id} उसे सूची से हटाता है और उसका इतिहास रखता है।
• —इनमें से हर एक को keys:manage चाहिए। कॉल करने वाली कुंजी को ख़ुद रोटेट करना keys:write से भी होता है, ठीक POST /keys/self/rotate की तरह।

हर बदलाव उस कुंजी के मुक़ाबले जाँचा जाता है जो उसे करती है। जो कुंजी किसी भी अक्ष पर कॉल करने वाले से बाहर चली जाए, उसे 403 beyond_caller_authority के साथ ठुकराया जाता है, और param उस अक्ष का नाम देता है:

• —स्कोप: सिर्फ़ वे जो कॉल करने वाले के पास उसकी अपनी भूमिका द्वारा सीमित किए जाने के बाद हैं।
• —भूमिका: किसी भूमिका से सीमित कॉल करने वाला सिर्फ़ उसी भूमिका से सीमित कुंजियाँ बना और संभाल सकता है।
• —समाप्ति: जिस कॉल करने वाले की समाप्ति है वह सिर्फ़ ऐसी कुंजियाँ बना और संभाल सकता है जो उससे बाद में समाप्त न हों।
• —मोड: टेस्ट कुंजी सिर्फ़ टेस्ट कुंजियों तक पहुँचती है।
• —भेजने का दायरा: सिर्फ़ कॉल करने वाले के अपने दायरे के भीतर के डोमेन और पते, और एक पता रखना कभी उसके पूरे डोमेन को कवर नहीं करता।

कंसोल कुंजी बनाने या रोटेट करने से पहले आपसे दोबारा सत्यापन करवाता है। कुंजी से की गई कॉल से यह नहीं माँगा जा सकता, इसलिए keys:manage ऐसा क्रेडेंशियल है जो क्रेडेंशियल बनाता है: इसे रखने वाली लीक हुई कुंजी अपनी पहुँच तक अपनी कुंजियाँ बना सकती है, जो उसके रद्द होने के बाद भी काम करती रहती हैं।

• —keys:manage सिर्फ़ उस ऑटोमेशन को दें जिसका काम कुंजियाँ जारी करना है, कभी ईमेल भेजने वाली कुंजी को नहीं।
• —उस कुंजी को सीमित करें: एक भूमिका, एक भेजने का दायरा और एक समाप्ति। वह जो कुछ बनाती है उसे तीनों विरासत में मिलते हैं और वह उनसे कभी आगे नहीं जा सकता।
• —GET /keys/activity पर नज़र रखें। वह जो भी कुंजी बनाती, बदलती या रद्द करती है वह नाम सहित उसी के खाते में दर्ज होती है, इसलिए लीक उन कुंजियों के रूप में दिखता है जिनकी आपको उम्मीद नहीं थी।
• —keys:read अनुरोध लॉग को, IP पतों और यूज़र एजेंट समेत, उजागर करता है। इसे ऑडिट एक्सेस की तरह मानें।

GET /keys/requests और GET /keys/{id}/requests किसी कुंजी की हर प्रमाणित कॉल पढ़ते हैं, सबसे नई पहले: मेथड, पाथ, स्थिति, एरर कोड, अवधि, IP और यूज़र एजेंट, कभी बॉडी या क्वेरी स्ट्रिंग नहीं। keyIds, failedOnly, since और until वे फ़िल्टर हैं जो कंसोल देता है। GET /keys/activity और GET /keys/{id}/activity पढ़ते हैं कि कुंजियों के साथ क्या हुआ, और actor बताता है कि यह किसने किया, @username या API key <name> के रूप में। कुछ भी हटाया नहीं जाता, और हटाई गई कुंजी अपना इतिहास रखती है।