# AI एजेंट के लिए API वर्जन अपग्रेड सुरक्षा

API वर्जन अपग्रेड एजेंट के अधिकार बढ़ा सकता है, भले ही एजेंट के निर्देशों की एक भी पंक्ति न बदले। खतरनाक बदलाव अक्सर रिलीज नोट में मामूली लगते हैं: कोई डिफॉल्ट बदल जाता है, नया एंडपॉइंट जुड़ जाता है, legacy token को compatibility path मिल जाता है या रिस्पॉन्स में वे रिकॉर्ड आने लगते हैं जो पुराने वर्जन में नहीं आते थे।

मानव द्वारा चलाए जाने वाले इंटीग्रेशन कभी-कभी इस अस्पष्टता से बच जाते हैं, क्योंकि व्यक्ति अनजान स्क्रीन देखकर रुक सकता है या अजीब अनुरोध से पहले सोच सकता है। स्वायत्त coding agent ऐसा विराम खुद नहीं लेता। अगर वह दस्तावेज से अनुरोध बना सकता है, errors देख सकता है और दूसरे विकल्प आजमा सकता है, तो हर नई उपलब्ध कार्रवाई उसके व्यावहारिक अधिकार का हिस्सा बन जाती है।

## वर्जन लेबल अधिकार नहीं मापते

वर्जन नंबर API provider की compatibility promise बताता है, एजेंट के अनुभव में आया permission change नहीं। हर API upgrade को authority review मानें, जब तक आप यह न देख लें कि credential पहले और बाद में क्या कर सकता था।

Semantic Versioning specification के अनुसार incompatible public API change होने पर MAJOR वर्जन बदलता है। इससे library maintainers तय कर सकते हैं कि callers टूट सकते हैं या नहीं। यह नहीं कहता कि MINOR release नया administrative endpoint नहीं जोड़ सकता, default filter को व्यापक नहीं कर सकता या किसी दूसरे audience का access token स्वीकार नहीं कर सकता। ये बदलाव compatibility बचाए रखते हुए भी एजेंट की क्षमता बढ़ा सकते हैं।

टीम अक्सर गलत सवाल पूछती है: «क्या हमारा code अब भी चलेगा?» खाते की सुरक्षा करने वाला सवाल है: «यह मौजूदा एजेंट अब कौन सी operations सफलतापूर्वक कर सकता है, किन resources पर और किस credential से?»

API upgrade के चार अलग surfaces हैं:

- **Request compatibility:** methods, paths, parameters और payload formats।
- **Resource reach:** वे accounts, projects, repositories, files या records जिन्हें अनुरोध छू सकता है।
- **Action reach:** read, write, delete, deploy, billing और identity operations जो पूरी हो सकती हैं।
- **Credential acceptance:** provider किन tokens, keys, signatures, audiences और scopes को स्वीकार करता है।

Request compatibility का green test बाकी तीन के बारे में लगभग कुछ नहीं बताता। इसी वजह से सामान्य regression suite पास होने के बाद भी एजेंट को production data तक नया रास्ता मिल सकता है।

यह न मानें कि dated API version इस समस्या को हल कर देता है। Provider shared authentication service बदल सकता है, agent को मिलने वाले opt-in fields जोड़ सकता है या endpoint path से बाहर defaults बदल सकता है। Version pin करना उपयोगी है। उसे permission boundary मानना लापरवाही है।

## पहले और बाद का authority map बनाएं

केवल changelog से upgrade की समीक्षा नहीं हो सकती। उन requests का छोटा map बनाएं जिन्हें एजेंट भेज सकता है और पुराने तथा नए वर्जन में वास्तविक व्यवहार की तुलना करें।

इच्छित design से नहीं, वास्तविक traffic से शुरू करें। एजेंट अक्सर मूल task से ज्यादा endpoints इस्तेमाल करते हैं: discovery calls, validation error के बाद retries, pagination, names को IDs में बदलने वाले lookup endpoints और error messages से सुझाए गए convenience APIs। इन calls को भी शामिल करें, क्योंकि वे resource identifiers दिखा सकते हैं या planned action से व्यापक रास्ता दे सकते हैं।

हर request family के लिए यह दर्ज करें:

| Field | क्या दर्ज करें |
|---|---|
| Operation | HTTP method और normalized path, जैसे `POST /v2/projects/{id}/deployments` |
| Resource boundary | tenant, project, repository, environment या record class जिसे यह छू सकता है |
| Credential | token class या API key label, secret नहीं |
| Authorization condition | scope, role, audience, user grant या server-side rule |
| Default behavior | optional filters, page limits और target fields न होने पर क्या होता है |
| Denial expectation | निषिद्ध resource और action के लिए अपेक्षित status और error |

Map में resource boundary साधारण भाषा में लिखें। «Can call deployments API» बहुत अस्पष्ट है। «Can create deployments only in the sandbox project» को test किया जा सकता है। अगर provider इतनी जानकारी नहीं देता, तो सीमा तय होने तक agent के लिए अलग test identity इस्तेमाल करें।

फिर दो-column comparison बनाएं। पुराने और नए वर्जन पर वही request corpus एक isolated account से चलाएं। उसमें अलग-अलग resources रखें: कम से कम एक allowed project, एक forbidden project, एक inactive record और, यदि service tenancy को support करती है, किसी दूसरे tenant का account। Test data के नाम पहचानने योग्य हों, ताकि accidental spillover दिख सके।

केवल status codes की तुलना न करें। `200` response में असली अंतर छिपा हो सकता है: दोगुने records, boundary पार करने वाला नया `next_page` link, अतिरिक्त credential field या ऐसा object identifier जो बाद में privileged endpoint को call करने दे। Response shape और identifiers की तुलना करें और नए fields को follow-on authority के लिए जांचें।

## बदले हुए defaults अनचाहे access paths बनाते हैं

छूटा हुआ parameter भी authorization decision है, जब server उसका अर्थ चुनता है। Changed defaults की समीक्षा नए write endpoint जैसी ही करें।

आम स्थिति एक harmless-looking list request से शुरू होती है। Version one में `project_id` जरूरी है और केवल active records लौटते हैं। Version two में `project_id` छोड़ा जा सकता है और provider इसका अर्थ «इस token को दिखने वाले सभी projects» मानता है। Agent का source code नहीं बदला, क्योंकि वह field पहले भी छोड़ रहा था। लेकिन उसका reachable data बदल गया।

ऐसे ही अन्य defaults भी पहुंच बढ़ा सकते हैं:

- list endpoint archived, deleted या inherited objects शामिल करने लगे;
- pagination छोटे fixed result set से cursor traversal और `next` URL पर चली जाए;
- create endpoint missing workspace ID पर request अस्वीकार करने के बजाय caller का default workspace चुन ले;
- update endpoint omitted fields को «current value बनाए रखें» माने;
- search endpoint connected services की सामग्री index करने लगे।

Provider इन्हें सुधार कहता है, क्योंकि client का काम घटता है। Agent के लिए client का कम काम अक्सर व्यापक target तक पहुंचने से पहले कम रुकावट का अर्थ होता है।

जानबूझकर अधूरे requests से defaults की समीक्षा करें। हर optional parameter के लिए उसे हटाकर, API अनुमति दे तो empty value के साथ और explicit safe value के साथ request भेजें। Target set और server error की तुलना करें। Documentation example में field छूटी हो तो agent उसे स्वाभाविक रूप से छोड़ेगा।

इसे «केवल project A इस्तेमाल करो» जैसे prompt text पर न छोड़ें। Prompt request choice को प्रभावित करता है, लेकिन API तय करता है कि request project B को छू सकती है या नहीं। Project boundary credential, endpoint design या request भेजने से पहले उसे validate करने वाले gateway में रखें।

## नए endpoints broad credentials को और broad बनाते हैं

अगर कोई credential नए endpoint पर authenticate कर सकता है, तो वह endpoint उसके अधिकार बढ़ाता है। Upgrade से पहले agent ने उसे call न किया हो, तब भी risk मौजूद है।

नई routes को अक्सर «new functionality» कहकर review से बाहर रखा जाता है। यह तर्क तभी चलता है जब human user को नया UI control मिले और administrator अलग से access दे। Broad scope वाला bearer token नई route पर अपने-आप चलने लगे, तो यह तर्क विफल है।

मान लें agent के पास `projects:write` token है। Version one में token project metadata बना और बदल सकता है। Version two में `POST /projects/{id}/exports` जुड़ता है, जो downloadable export बनाता है और वही scope इस्तेमाल करता है। Scope string नहीं बदली, लेकिन token रखने का प्रभाव बदल गया। Agent endpoint को API schema, generated client, error hint या documentation से खोज सकता है।

नई routes को HTTP verb से नहीं, प्रभाव से वर्गीकृत करें। `GET` source code, secret values, audit history, personal data या signed download URLs दिखा सकता है। `POST` irreversible cost या external workflow शुरू कर सकता है। `DELETE` route से कम खतरनाक कोई `GET` route हो सकती है जो कहीं और इस्तेमाल होने वाला credential दिखा दे।

हर नई route पर चार सवाल पूछें:

1. क्या मौजूदा agent credential सफलतापूर्वक authenticate करता है?
2. कौन से मौजूदा scopes, roles या API-key classes इसे अनुमति देते हैं?
3. क्या output किसी दूसरी operation के लिए identifiers, URLs या tokens दे सकता है?
4. क्या agent client library, discovery document या दिए गए documentation से वहां पहुंच सकता है?

«हम agent को नए endpoint के बारे में नहीं बताएंगे» कोई control नहीं है। Agent schema देख सकता है, सामान्य paths का अनुमान लगा सकता है या बाद के task से निर्देश पा सकता है। Server को unapproved operation अस्वीकार करनी चाहिए, चाहे client को exact URL मालूम हो।

अगर provider नई route को पुराने broad scope से अलग नहीं कर सकता, तो upgrade से पहले narrower integration identity बनाएं। किसी एक workflow के लिए बनाया गया token provider द्वारा scope name को दिए जाने वाले हर भविष्य के अर्थ को inherit न करे।

## Authentication में बदलाव permission change है

Upgrade review में authentication behavior भी शामिल करें, क्योंकि credential को अलग तरह से स्वीकार करना यह बदलता है कि कौन कार्रवाई कर सकता है। Teams अक्सर successful login test करती हैं और denial cases छोड़ देती हैं, जबकि नुकसान वहीं होता है।

OAuth 2.0 access tokens को authorization grant दर्शाने वाले credentials के रूप में परिभाषित करता है। RFC 9700, OAuth 2.0 Security Best Current Practice, exact redirect URI matching और token replay तथा sender-constrained tokens से जुड़े protections की बात करता है। व्यापक lesson यह है कि token का format अकेले उसके intended recipient, sender या scope को साबित नहीं करता। Resource server को हर accepted request पर इन properties को लागू करना चाहिए।

Version changes इस enforcement को अप्रत्यक्ष रूप से बदल सकते हैं। Provider नया issuer ला सकता है, sibling API के tokens स्वीकार कर सकता है, token exchange route जोड़ सकता है, refresh-token rotation बदल सकता है या scoped token के साथ legacy API key भी मान सकता है। Compatibility का दबाव ऐसे बदलावों को आकर्षक बनाता है, लेकिन इससे वे alternate paths बनते हैं जिन्हें engineers test करना भूल जाते हैं।

Acceptance और rejection दोनों test करें। हर credential class के लिए allowed operation, forbidden resource पर वही operation, expired credential, गलत audience वाला token, missing scope वाला token और revoked credential आजमाएं। Refresh tokens हों तो देखें कि refresh पुराना grant रखता है, audience बदलता है या बाद की consent flow में दिए गए scopes चुपचाप जोड़ता है।

एक उपयोगी record ऐसा दिख सकता है:

```text
credential: build-agent-sandbox
request: POST /v3/projects/prod-42/deployments
expected: 403 forbidden
old version: 403 {"error":"insufficient_scope"}
new version: 201 {"id":"dep_...","environment":"production"}
review result: block upgrade and revoke credential
```

Response body महत्वपूर्ण है। `403` का `404` बनना जानबूझकर information hiding हो सकता है। `403` का `201` बनना authority increase है, चाहे changelog इसे improved compatibility कहे।

Headers भी देखें। Custom headers API version, organization या impersonated user चुन सकते हैं। अगर नया API missing header को default organization मानता है, तो header formatting error के बाद agent का retry गलत जगह पहुंच सकता है। Secrets हटाकर exact headers दर्ज करें और omission को अलग से test करें।

## Agent behavior छोटे बदलावों को पूरे workflow में बदल देता है

Agent अलग-अलग सामान्य calls को जोड़कर ऐसा परिणाम बना सकता है जिसकी designer ने एक permission के रूप में समीक्षा नहीं की। Version review में इन chains को भी शामिल करें।

नया list field repository ID दिखा सकता है। वह ID download endpoint में जा सकती है। Download response signed URL दे सकता है और URL ऐसा artifact दिखा सकता है जिसके configuration में किसी दूसरी service का endpoint हो। हर call अकेले allowed लग सकती है, लेकिन पूरी sequence agent को मिले task से आगे जा सकती है।

इसीलिए endpoint-by-endpoint authorization review जरूरी होते हुए भी अधूरी है। Agent से करवाने वाली actions और रोकने वाली nearby actions के workflow tests जोड़ें। Calls के बीच identifier flow trace करें: IDs, pagination cursors, locations, presigned URLs, job IDs और valid resource names बताने वाले error messages।

Tests को ठोस रखें। यदि agent को एक repository में issue update करना है, तो जांचें कि वह:

- सही issue पढ़ और अनुमत fields बदल सकता है;
- दूसरी repository के issue ID पर असफल होता है;
- repository settings या webhooks बदलने पर असफल होता है;
- export, member list या token management route की link follow करने पर असफल होता है।

Failure path success path जितना ही महत्वपूर्ण है। Agent errors को information की तरह इस्तेमाल करता है। Detailed denial में alternate endpoint का नाम देना अनचाही route खोजने को आसान बना सकता है। Human developers के लिए यह tradeoff स्वीकार्य हो सकता है, लेकिन autonomous process को integration देने से पहले इसका पता होना चाहिए।

Upgrade tests में retries सीमित रखें। Idempotent request के समय harmless retry policy duplicate action बना सकती है, अगर नया वर्जन idempotency handling बदल दे या काम पूरा करने के बाद timeout लौटाए। देखें कि API idempotency key इस्तेमाल करता है या नहीं, उसे कितनी देर रखता है और upgrade header name या request hashing rules बदलता है या नहीं।

## Capability diff वे बदलाव पकड़ता है जिन्हें सामान्य tests छोड़ देते हैं

Capability diff एक repeatable test है जो पूछता है कि credential कौन से requests पूरे कर सकता है, न कि application को expected data अब भी मिल रहा है या नहीं। इसे इतना छोटा रखें कि हर version candidate पर चल सके।

ऐसा request corpus repository में बनाएं जिसमें production secrets न हों। Test tokens के लिए environment variables इस्तेमाल करें और केवल disposable account को target करें। यह shell pattern बदले हुए authority के संकेत दर्ज करता है, बिना credential output किए:

```sh
curl -sS -D headers.txt -o body.json \
  -H "Authorization: Bearer $TEST_TOKEN" \
  -H "X-API-Version: 2025-01-01" \
  "https://api.example.test/v1/projects?limit=2"

printf 'status: ' && head -n 1 headers.txt
printf 'headers:\n' && grep -Ei '^(link|location|x-request-id|www-authenticate):' headers.txt
printf 'identifiers:\n' && jq -r '.. | objects | (.id? // empty)' body.json | sort -u
```

हर वर्जन के लिए corpus चलाएं और status, चुने हुए headers तथा normalized identifiers की तुलना करें। पूरे JSON का blind diff न करें। Timestamps, request IDs और ordering noise बनाते हैं। पहले इन fields को normalize करें, लेकिन pagination links, resource IDs, role names और बाद के request को निर्देशित करने वाली हर field बचाकर रखें।

Corpus में successful requests, expected denials, missing optional parameters और first page के साथ pagination follow-up शामिल करें। मौजूदा agent scope से संबंधित हर नए documented route के लिए एक request जोड़ें। लक्ष्य पूरे provider की सूची बनाना नहीं, बल्कि उन operations को cover करना है जिन्हें agent वास्तव में खोज या जोड़ सकता है।

एक सरल result file निर्णयों को reviewable बनाती है:

```json
{
  "case": "forbidden-production-deploy",
  "credential": "build-agent-sandbox",
  "request": "POST /v3/projects/prod-42/deployments",
  "expected_status": 403,
  "observed_status": 403,
  "observed_resource_ids": [],
  "version": "2025-01-01"
}
```

हर difference पर reviewer का स्पष्ट निर्णय जरूरी करें। «Provider ने ऐसा बदल दिया» निर्णय नहीं है। Reviewer को बताना चाहिए कि नया behavior agent के approved authority के भीतर है या नहीं और, यदि है, तो वह authority कहां लागू होती है।

## Logs बताते हैं क्या हुआ, क्या होना चाहिए था नहीं

Request logs upgrade की जांच में मदद करते हैं, लेकिन pre-deployment authority review की जगह नहीं लेते। दोनों अलग सवालों का जवाब देते हैं।

Upgrade से पहले capability diff बताता है कि provider unwanted request स्वीकार करेगा या नहीं। Upgrade के बाद logs बताते हैं कि agent ने उसे वास्तव में आजमाया या नहीं, किस process ने कोशिश की और account को नियंत्रित करने की जरूरत है या नहीं। दोनों जरूरी हैं, क्योंकि आज denied request कल provider-side बदलाव के बाद accepted हो सकती है।

Version selector, normalized operation, target boundary, credential label, decision, status और correlation ID log करें। Bearer tokens, raw authorization headers, full request bodies या secret वाले response fields log न करें। जिस credential को बचाना था, वही security log में रख देना breach को सिर्फ दूसरी जगह ले जाना है।

Session record और action record अलग रखें। Session बताता है कि run के दौरान किस agent process को काम करने की अनुमति मिली। Action record बताता है कि उसने कौन सा individual request किया। यह अंतर तब महत्वपूर्ण होता है जब long-running agent reviewed version से शुरू होकर बाद में environment change या regenerated client library पा ले।

Sallyport एक encrypted, hash-chained audit log से Sessions journal और Activity journal बनाता है, इसलिए operator agent run और हर HTTP या SSH action दोनों देख सकता है। इसका offline `sp audit verify` check vault तक पहुंच के बिना chain जांच सकता है, जो upgrade review के incident review में बदलने पर उपयोगी है।

Tamper evidence को prevention न समझें। सही audit trail यह साबित कर सकती है कि नया endpoint इस्तेमाल हुआ, लेकिन remote service से exported data वापस नहीं खींच सकती। Sensitive actions को ऐसे credentials और approvals के पीछे रखें जो request machine से निकलने से पहले fail हो जाएं।

## Approval अस्पष्ट task से नहीं, process से जुड़ी होनी चाहिए

Human approval तभी unreviewed upgrade रोक सकती है जब वह बताए कि कौन सा executable authority मांग रहा है। «Agent API access चाहता है» पर्याप्त जानकारी नहीं है, खासकर जब कई local processes वही protocol बोल सकते हों।

जहां operating system यह सुविधा देता है, requesting process की code-signing authority से session authorization जोड़ें। इससे substitution failure पकड़ी जाती है: trusted agent session शुरू करता है, फिर untrusted helper या copied binary वही credential route इस्तेमाल करने की कोशिश करता है। Process identity यह साबित नहीं करती कि हर future request सही होगी, लेकिन operator को approve या revoke करने के लिए ठोस object देती है।

Per-call approval उन credentials के लिए रखें जिनका प्रभाव सीमित करना स्वभाव से कठिन है, जैसे production deployment, account administration या data export। हर harmless read पर व्यक्ति से मंजूरी मांगना approval cards पर बिना सोचे click करना सिखाता है। Approval fatigue design error है, user की गलती नहीं।

Sallyport fixed three-control decision ladder इस्तेमाल करता है: locked vault सभी actions रोकता है, नया agent process default रूप से session authorization मांगता है और per-key setting हर use पर अलग approval मांग सकती है। यह हर संगठनात्मक नियम व्यक्त नहीं करेगी, लेकिन authority changes को policy syntax के ढेर में छिपने से रोकती है।

जब API upgrade credential का effective scope बदल दे, तो current session revoke करें और review के बाद fresh approval लें। कल की endpoint set के लिए approved session को कल के व्यापक endpoint पर चुपचाप जारी न रहने दें।

## Authority review को release gate बनाएं

API version upgrade release gate पर तब रुकना चाहिए जब current credential को कोई unexplained successful request मिले, denied request permitted हो जाए या response ऐसा नया identifier दिखाए जो निषिद्ध workflow को सक्षम करे।

Review को dependency updates और generated-client changes वाले उसी change record में रखें। पुराने और नए API selectors, provider release notes, capability diff output, tested credential classes और हर intentional difference स्वीकार करने वाले व्यक्ति का नाम दर्ज करें। यह साधारण काम है, इसलिए पहली अजीब audit entry आने तक अक्सर छोड़ दिया जाता है।

Major API version का इंतजार न करें। Provider API version, authentication service, OAuth application settings, generated SDK, discovery schema, default header या scope definition बदले तो review शुरू करें। URL के बाहर हुआ बदलाव भी remote server का निर्णय बदल सकता है।

उस credential से शुरू करें जिसे एक अतिरिक्त route मिलने पर सबसे ज्यादा नुकसान होगा। उसे isolated test account दें, पांच allowed और denied requests लिखें और proposed version पर चलाएं। यदि आप यह नहीं बता सकते कि हर success agent के काम का हिस्सा क्यों है, तो integration autonomous use के लिए तैयार नहीं है।