For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 से मेल खाए:

एंडपॉइंट
आवश्यक scope

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 मौजूद ही नहीं है - देखें त्रुटियाँ.

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 आवश्यक हैं.

protected

boolean

key को एक protected स्थिति में बनाएँ.

scopes बनाते समय:

  • छोड़ा गया - नई key calling credential के अपने scopes विरासत में लेती है ("मेरी तरह एक key बनाएँ"). यह plan-independent है: एक full-access key एक full-access key बनाती है; एक scoped key उन्हीं scopes वाली key बनाती है; folders भी इसी तरह विरासत में मिलते हैं। जो script scopes Advanced 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"}}. देखें त्रुटियाँ.

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 है protected. पहले Roboflow dashboard में इसे unprotect करें.

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 के scopes call करने वाली key के scopes का उपसमुच्चय होना चाहिए, और इसके folderIds call करने वाली 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"}

एक आम गलती: जिस अनुरोध के क्रेडेंशियल में बस उस रूट का स्कोप नहीं है, वह लौटाता है 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 बदलता है कुंजी के मौजूदा स्कोप्स को ठीक उसी सेट से बदलता है जो आप पास करते हैं, और --metadata कुंजी के मेटाडेटा को बदल देता है। भेजें --name इनमें से किसी को छुए बिना केवल नाम बदलने के लिए अकेले।

कुंजी को सुरक्षित करें / असुरक्षित करें

एक संरक्षित कुंजी को CLI, API, या MCP के माध्यम से अक्षम या रद्द नहीं किया जा सकता। असुरक्षित करना केवल में किया जा सकता है dashboard - जानबूझकर कोई unprotect कमांड नहीं है, इसलिए कोई स्वचालित वर्कफ़्लो सुरक्षा हटाकर एक ही चरण में प्रोडक्शन कुंजी को रद्द नहीं कर सकता।

कुंजी को अक्षम / पुनः सक्षम करें

अक्षम कुंजियाँ API द्वारा अस्वीकार कर दी जाती हैं, लेकिन उन्हें फिर से सक्षम किया जा सकता है। एक संरक्षित कुंजी को अक्षम नहीं किया जा सकता।

कुंजी रद्द करें

रद्द करना स्थायी है। एक संरक्षित कुंजी को CLI से रद्द नहीं किया जा सकता - पहले उसे डैशबोर्ड में असुरक्षित करें।

प्रकाशित करने योग्य कुंजी प्राप्त करें

प्रकाशित करने योग्य कुंजी (rf_<workspaceId>) गैर-सीक्रेट है और ब्राउज़र / inferencejs कोड में एम्बेड करने के लिए सुरक्षित है। यह केवल inference के लिए है और इसे बनाया या रद्द नहीं किया जा सकता। देखें प्रकाशनीय कुंजी विवरण के लिए।

अंतिम अपडेट

क्या यह उपयोगी था?