API Keys प्रबंधित करें
Roboflow REST API, roboflow api-key CLI, या MCP server के साथ workspace API keys को programmatically create, list, update, protect, और revoke करें।
के बारे में
आप Roboflow API का उपयोग करके प्रोग्रामेटिक रूप से अपने workspace की API keys प्रबंधित कर सकते हैं - नई keys बनाएं, मौजूदा keys की सूची देखें और उनकी जाँच करें, उनका नाम बदलें, metadata जोड़ें, उन्हें disable करें, protect करें, और revoke करें।
यह वही इंटरफ़ेस है जिसका उपयोग roboflow api-key CLI और Roboflow MCP सर्वर, ताकि एक स्वचालित agent dashboard से किसी इंसान के copy-paste किए बिना किसी application के लिए आवश्यक key provision कर सके।
Secrets एक बार ही लिखे जा सकते हैं। पूरी key value वापस दी जाती है केवल जब आप कोई key बनाते हैं (या roll करते हैं)। बाकी सभी endpoint एक non-secret लौटाते हैं keyId handle के साथ एक छोटा prefix पहचान के लिए - कभी भी असली key नहीं। value को सुरक्षित रूप से संग्रहीत करें (जैसे एक .gitignore'd .env) creation के समय.
HTTP API
प्रमाणीकरण
अपनी API key को इस रूप में भेजें api_key query parameter या एक Authorization: Bearer <api_key> header, जैसा कि हर दूसरे REST endpoint में होता है (देखें REST API से प्रमाणीकरण करें). उपयोग में लाई जा रही key path में दिए गए workspace से संबंधित होनी चाहिए।
ये endpoints Roboflow की भूमिकाओं और अनुमतियोंका पालन करते हैं। जब caller एक किसी user के लिए काम कर रहा OAuth token, तो संबंधित RBAC actions (create_api_key, update_api_key, revoke_api_key, get_api_key, view_workspace_api_keys) डिफ़ॉल्ट रूप से workspace के owners/admins. scoped key (या किसी user के लिए काम कर रहे OAuth token) के साथ किया गया request केवल वही क्षमताएँ बना या प्रदान कर सकता है जो caller के पास पहले से स्वयं हैं - देखें विशेषाधिकार उपसमुच्चय नियम.
जब caller एक scoped (non-OAuth) private key, तो उसमें अतिरिक्त रूप से scope होना चाहिए जो endpoint से मेल खाए:
GET सूची / GET एक
api-key:read
POST बनाना
api-key:create
PATCH अपडेट
api-key:update
DELETE रद्द करना
api-key:revoke
GET publishable
workspace:read
एक unscoped (पूर्ण-एक्सेस) private key पहले से ही इन सभी को पूरा करती है। आवश्यक scope के बिना key को ऐसे माना जाता है जैसे route मौजूद ही नहीं है - देखें त्रुटियाँ.
एक publishable key (rf_<workspaceId>) है नहीं इन management endpoints के लिए authentication के रूप में स्वीकार नहीं की जाती। किसी private key से authenticate करें।
API Keys की सूची
GET /:workspace/api-keys
workspace की API keys (masked) की सूची दिखाता है और workspace की publishable key लौटाता है।
Query
api_key
string
workspace के लिए एक private API key.
includeDisabled
boolean
परिणाम में disabled keys शामिल करें (डिफ़ॉल्ट false).
includeFolders
boolean
folder-scoped keys के लिए folder विवरण भरें (डिफ़ॉल्ट false).
उदाहरण अनुरोध
प्रतिक्रिया
नोट्स:
keyIdएक स्थिर, non-secret handle है जिसका उपयोग अन्य endpoints में किसी key को संबोधित करने के लिए किया जाता है।scopesहैnullएक unscoped (पूर्ण-एक्सेस) key के लिए, या एक array scope strings scoped key के लिए.created_on(ISO 8601) तथाcreated_byकेवल उन keys के लिए शामिल किए जाते हैं जिनमें वे मान रिकॉर्ड किए गए हों। इस attribution को ट्रैक करने से पहले बनाई गई पुरानी keys में ये शामिल नहीं होते।created_byएक opaque पहचानकर्ता है कि key किसने बनाई - एक user id,api_key:<handle>(जब key किसी दूसरी API key द्वारा बनाई गई हो), याSYSTEM(एक स्वचालित प्रक्रिया द्वारा बनाई गई)। इसे display/audit string के रूप में समझें; इसका parse न करें।custom_metadataशामिल होता है केवल जब workspace की plan में Advanced API Keys शामिल हों। उस सुविधा के बिना यह field पूरी तरह अनुपस्थित रहती है (यहाँ तक कि उन keys के लिए भी जिनमें metadata हो).
एकल API Key प्राप्त करें
GET /:workspace/api-keys/:keyId
एक key के लिए masked metadata लौटाता है, जिसे उसके keyId handle से संबोधित किया जाता है।
उदाहरण अनुरोध
प्रतिक्रिया
ऐसी कोई key keyId workspace में मौजूद नहीं है (या उसे revoke कर दिया गया है), या credential में api-key:read scope नहीं है / यह ऐसे workspace को लक्षित करता है जिससे यह संबंधित नहीं है। permission वाला मामला object-आकृति का error लौटाता है {"error": {"message", "type", "hint"}}; एक अज्ञात keyId लौटाता है {"error": "string"}. देखें त्रुटियाँ.
API Key बनाएँ
POST /:workspace/api-keys
एक नई API key बनाता है। secret value वापस दी जाती है केवल एक बार में key field.
Headers
Content-Type
application/json
Body
name
string
key के लिए एक उपयोगकर्ता-अनुकूल label.
scopes
Array<string> | null
key को इन तक सीमित करें scopes. नीचे दी गई तीन अवस्थाएँ देखें. Advanced API Keys आवश्यक हैं.
folderIds
Array<string>
key को इन project folders तक सीमित करें. Advanced API Keys आवश्यक हैं.
custom_metadata
Map<string, string>
अधिकतम 20 key/value जोड़े (keys ≤100 वर्ण, values ≤500 वर्ण). Advanced API Keys आवश्यक हैं.
scopes बनाते समय:
छोड़ा गया - नई key calling credential के अपने scopes विरासत में लेती है ("मेरी तरह एक key बनाएँ"). यह plan-independent है: एक full-access key एक full-access key बनाती है; एक scoped key उन्हीं scopes वाली key बनाती है; folders भी इसी तरह विरासत में मिलते हैं। जो script
scopesAdvanced API Keys सुविधा workspace में हो या न हो, समान व्यवहार करती है।null- एक स्पष्ट पूर्ण-एक्सेस (unscoped) key। caller के पास स्वयं full access होना चाहिए (scoped caller अस्वीकार किया जाता है - देखें उपसमुच्चय नियम).[](empty array) - एक वैध key जिसके पास कोई क्षमता नहीं; हर scoped route इसे अस्वीकार करता है। बाद में scopes देने के लिए placeholder के रूप में उपयोगी.["model:infer", …]- scoped ठीक उन्हीं क्षमताओं तक (एक section name जैसेmodelउस section के सभी scopes प्रदान करता है).["role:reviewer", …]- एक role preset: create समय पर उस role के scopes में विस्तारित होता है। एक built-in role (labeler,reviewer,owner) या किसी custom role का नाम;role:ownerका अर्थ full access है। स्पष्ट scopes के साथ संयोज्य.
एक स्पष्ट scopes array ([], एक list, या एक role: preset), folderIds, या custom_metadata के लिए Advanced API Keys plan सुविधा आवश्यक है (अन्यथा 403). छोड़ना scopes (inherit) और null (full) नहीं करते - इसलिए default हर plan पर काम करता है।
उदाहरण अनुरोध
प्रतिक्रिया
caller को keys बनाने की अनुमति है लेकिन उसने अपने पास मौजूद अधिकारों से अधिक scopes/folders देने का अनुरोध किया, या workspace plan में अनुरोधित advanced feature शामिल नहीं है। Body: {"error": "string"}.
credential में api-key:create scope नहीं है, या यह ऐसे workspace को लक्षित करता है जिससे यह संबंधित नहीं है। Body: {"error": {"message", "type", "hint"}}. देखें त्रुटियाँ.
यह key field secret value है और दिखाई जाती है केवल इस response में। इसे अभी सहेज लें; आप इसे दोबारा प्राप्त नहीं कर सकते.
API Key अपडेट करें
PATCH /:workspace/api-keys/:keyId
key का नाम, scopes, या metadata अपडेट करता है; उसे protect करता है; या उसे enable/disable करता है.
Headers
Content-Type
application/json
Body (केवल वही fields भेजें जिन्हें आप बदलना चाहते हैं)
name
string
नया display name.
scopes
Array<string> | null
नया scopes (caller के उपसमुच्चय का)। नीचे दी गई तीन अवस्थाएँ देखें. Advanced API Keys आवश्यक हैं.
custom_metadata
Map<string, string>
key का metadata बदल देता है. Advanced API Keys आवश्यक हैं.
protected
true
key को protect करें। API unprotect नहीं कर सकती - नीचे देखें.
disabled
boolean
Disable (true) या फिर से enable करें (false) key को. Advanced API Keys आवश्यक हैं.
की तीन अवस्थाएँ scopes (PATCH semantics create से थोड़ी भिन्न हैं - किसी field को छोड़ने पर वह अपरिवर्तित रहती है):
छोड़ा गया - key के मौजूदा scopes जैसे के तैसे रहते हैं.
null- key बन जाती है पूर्ण-एक्सेस (unscoped)। इसे देने के लिए caller के पास स्वयं full access होना चाहिए.[](empty array) - key के पास वैध credential बना रहता है लेकिन उसमें कोई क्षमता नहीं.["model:infer", …]- बदलता है key के scopes को बिल्कुल इसी set से (एक section name उस section के सभी scopes में विस्तारित होता है).
भेजने पर scopes (सहित [] या null), custom_metadata, या disabled के लिए Advanced API Keys plan सुविधा.
उदाहरण अनुरोध
प्रतिक्रिया
यदि आप भेजते हैं तो लौटाया जाता है "protected": false (API किसी key को unprotect नहीं कर सकती), या यदि आप ऐसे scopes माँगते हैं जिन्हें caller दे नहीं सकता। Body: {"error": "string"}.
ऐसी कोई key keyId workspace में (body: {"error": "string"}), या credential में api-key:update scope नहीं है / ऐसे workspace को लक्षित करता है जिससे यह संबंधित नहीं है (body: {"error": {"message", "type", "hint"}}). देखें त्रुटियाँ.
यदि आप किसी ऐसी key को disable करने की कोशिश करते हैं जो वर्तमान में protected.
API Key रद्द करें
DELETE /:workspace/api-keys/:keyId
key को revoke करता है (स्थायी रूप से निष्क्रिय करता है)। इसका उपयोग कर रहे मौजूदा applications तुरंत authenticate करने में विफल हो जाएँगे.
उदाहरण अनुरोध
प्रतिक्रिया
Key को Protect करना
एक protected key को disable या revoke नहीं किया जा सकता - API, CLI, MCP server, या dashboard - जब तक इसे unprotect न किया जाए। इसका उपयोग किसी स्वचालित agent को गलती से production key बंद करने से रोकने के लिए करें.
Protect करें:
PATCHके साथ{ "protected": true }.Unprotect: किया जा सकता है केवल में किया dashboard. API/CLI/MCP जानबूझकर किसी key को unprotect नहीं कर सकते, इसलिए कोई compromised या बहुत उत्साही agent सुरक्षा हटाकर फिर एक ही बार में key को revoke नहीं कर सकता.
प्रकाशनीय कुंजी
हर workspace के पास एक publishable key के रूप में rf_<workspaceId>. यह है:
कोई secret नहीं - client-side / browser code में embed करने के लिए सुरक्षित (जैसे. inferencejs).
केवल Inference + model-download - यह data को manage, train, या keys को manage नहीं कर सकती.
स्थायी - यह workspace ID से derived होती है, इसलिए इसे बनाया, rotate, या revoke नहीं किया जा सकता.
इसे यहाँ से पढ़ें publishableKey field list/create responses में, या सीधे:
GET /:workspace/api-keys/publishable
browser/edge inference के लिए publishable key का उपयोग करें और server-side काम के लिए scoped private key का। ध्यान दें कि publishable key रखने वाला कोई भी व्यक्ति उस workspace के models पर inference चला सकता है (और उन्हें डाउनलोड कर सकता है) - यही एक "publishable" credential का अपेक्षित trade-off है.
विशेषाधिकार उपसमुच्चय नियम
विशेषाधिकार वृद्धि को रोकने के लिए, नई बनाई गई या अपडेट की गई key के पास उसे बनाने वाले credential से अधिक क्षमताएँ कभी नहीं हो सकतीं:
जब आप इन endpoints को एक scoped private key, तो नई key के
scopescall करने वाली key के scopes का उपसमुच्चय होना चाहिए, और इसकेfolderIdscall करने वाली key के folders का उपसमुच्चय होना चाहिए। एक unscoped (पूर्ण-एक्सेस) key कुछ भी प्रदान कर सकती है.जब आप इन्हें एक किसी user के लिए काम कर रहा OAuth token, तो अनुरोधित scopes को अतिरिक्त रूप से उस user की role के विरुद्ध जाँचा जाता है - आप केवल वही क्षमताएँ दे सकते हैं जिनकी अनुमति आपकी role देती है.
जो अनुरोध caller की देने की क्षमता से अधिक हों, वे लौटाते हैं 403.
त्रुटियाँ
400
अमान्य request body (जैसे कोई अज्ञात scope, विकृत metadata).
{"error": "string"}
403
caller को route के लिए अनुमति है, लेकिन उसने अपनी धारित क्षमता से अधिक क्षमताएँ देने को कहा (scopes/folders जो caller से अधिक हैं), plan में Advanced API Keys नहीं हैं, या API के माध्यम से unprotect करने का प्रयास.
{"error": "string"}
404
या तो ऐसी कोई key keyId workspace में मौजूद नहीं है, या credential में उस route के लिए आवश्यक scope नहीं है, या यह ऐसे workspace को लक्षित करता है जिससे key संबंधित नहीं है। Roboflow जानबूझकर यह छिपाता है कि संसाधन मौजूद है या नहीं.
{"error": {"message", "type", "hint"}} permission/workspace मामले के लिए; {"error": "string"} एक अज्ञात keyId.
409
key protected है और उसे disable/revoke नहीं किया जा सकता.
{"error": "string"}
त्रुटि body के दो स्वरूप. अधिकांश endpoints एक string error - {"error": "Some message"}. इसके बजाय authentication/permission layer एक object - {"error": {"message": "…", "type": "…", "hint": "…"}} (permission/wrong-workspace 404 ऊपर, और किसी गायब या अमान्य कुंजी के लिए 401). ऐसे उपभोक्ता लिखें जो संभालें दोनों रूप।
एक आम गलती: जिस अनुरोध के क्रेडेंशियल में बस उस रूट का स्कोप नहीं है, वह लौटाता है 404, न कि 403. एक 403 का मतलब है कि कॉल है को कुंजियों को प्रबंधित करने की अनुमति थी, लेकिन उसने कॉलर के पास जितनी हैं उससे अधिक देने की कोशिश की।
देखें त्रुटियाँ और स्टेटस कोड सामान्य त्रुटि प्रारूप के लिए।
CLI
यह roboflow api-key कमांड समूह आपको टर्मिनल से अपने वर्कस्पेस की API कुंजियों को प्रबंधित करने देता है। यह लपेटता है API कुंजी REST एंडपॉइंट्स और आपके CLI कॉन्फ़िग से वर्कस्पेस और क्रेडेंशियल्स का उपयोग करता है (देखें CLI इंस्टॉल और सेट अप करें).
पूर्ण सीक्रेट मान दिखाया जाता है केवल जब आप कुंजी बनाते हैं। इसे तुरंत कैप्चर करें - list/get इसे फिर कभी प्रकट नहीं करते।
सूची
वर्कस्पेस की API कुंजियों की सूची दिखाएँ।
प्राप्त करें
एक कुंजी का विवरण दिखाएँ।
बनाना
एक नई कुंजी बनाएं (सीक्रेट केवल एक बार प्रिंट होता है)।
अपडेट
किसी कुंजी का नाम, स्कोप, या मेटाडेटा अपडेट करें।
संरक्षित करें
किसी कुंजी को संरक्षित के रूप में चिह्नित करें।
अक्षम करें
किसी कुंजी को अक्षम करें या फिर से सक्षम करें।
रद्द करना
किसी कुंजी को स्थायी रूप से रद्द करें।
publishable
वर्कस्पेस की प्रकाशित करने योग्य कुंजी प्रिंट करें।
जोड़ें --json (एक ग्लोबल फ्लैग, कमांड से पहले) ताकि स्क्रिप्टिंग के लिए मशीन-पठनीय आउटपुट मिले, जैसे roboflow --json api-key list.
कुंजियों की सूची
एक कुंजी प्राप्त करें
कुंजियों को उनके द्वारा संबोधित किया जाता है keyId (गैर-सीक्रेट हैंडल जो में दिखाया गया है सूची):
एक कुंजी बनाएं
सीक्रेट केवल एक बार प्रिंट होता है। इसे किसी स्क्रिप्ट में कैप्चर करने के लिए, उपयोग करें --json और पाइप करें jq:
--scope, --folderऔर --metadata Advanced API Keys प्लान फ़ीचर की आवश्यकता होती है, और आप केवल वही क्षमताएँ दे सकते हैं जो कमांड चलाने वाले क्रेडेंशियल के पास पहले से हों।
कुंजी अपडेट करें
--scope बदलता है कुंजी के मौजूदा स्कोप्स को ठीक उसी सेट से बदलता है जो आप पास करते हैं, और --metadata कुंजी के मेटाडेटा को बदल देता है। भेजें --name इनमें से किसी को छुए बिना केवल नाम बदलने के लिए अकेले।
स्कोप्स या मेटाडेटा बदलने के लिए Advanced API Keys प्लान फ़ीचर आवश्यक है (केवल नाम बदलना के साथ --name आवश्यक नहीं है)। बनाना, आप केवल वही स्कोप्स दे सकते हैं जो कमांड चलाने वाला क्रेडेंशियल पहले से रखता है।
कुंजी को सुरक्षित करें / असुरक्षित करें
एक संरक्षित कुंजी को CLI, API, या MCP के माध्यम से अक्षम या रद्द नहीं किया जा सकता। असुरक्षित करना केवल में किया जा सकता है dashboard - जानबूझकर कोई unprotect कमांड नहीं है, इसलिए कोई स्वचालित वर्कफ़्लो सुरक्षा हटाकर एक ही चरण में प्रोडक्शन कुंजी को रद्द नहीं कर सकता।
कुंजी को अक्षम / पुनः सक्षम करें
अक्षम कुंजियाँ API द्वारा अस्वीकार कर दी जाती हैं, लेकिन उन्हें फिर से सक्षम किया जा सकता है। एक संरक्षित कुंजी को अक्षम नहीं किया जा सकता।
roboflow api-key disable (और के साथ पुनः सक्षम करना --enable) के लिए Advanced API Keys प्लान फ़ीचर आवश्यक है, ठीक वैसे ही जैसे स्कोप्ड बनाना के साथ --scope/--folder. यह इससे मेल खाता है REST API.
कुंजी रद्द करें
रद्द करना स्थायी है। एक संरक्षित कुंजी को CLI से रद्द नहीं किया जा सकता - पहले उसे डैशबोर्ड में असुरक्षित करें।
प्रकाशित करने योग्य कुंजी प्राप्त करें
प्रकाशित करने योग्य कुंजी (rf_<workspaceId>) गैर-सीक्रेट है और ब्राउज़र / inferencejs कोड में एम्बेड करने के लिए सुरक्षित है। यह केवल inference के लिए है और इसे बनाया या रद्द नहीं किया जा सकता। देखें प्रकाशनीय कुंजी विवरण के लिए।
अंतिम अपडेट
क्या यह उपयोगी था?