Conversation
The Admin API is the reason most readers open these docs, and its introduction was selling a credential that no longer works: two tiers of API key, a permissions table built on who may create them, and a first request that never appears. Rebuild it as a page a reader can act on. Show the request first — token, call, refresh — then the two facts that explain most failures. Resources sit at the organisation level, reached by the TSG ID inside the token, or at the workspace level, reached by a `workspace_id` that is a query parameter on reads and a body field on writes. Paths take a slug where you named the resource and an ID where the gateway named it. Then the map: six groups against the real surface, and five common tasks written as the call sequences they actually are, because provisioning an integration to a team is three requests and the second and third are the ones people miss. No deep links to generated operation pages — those have neither titles nor stable URLs until `x-mint.href` lands upstream. Claims the old page made that the spec does not support are gone: there is no workspace or user CRUD in this API. The same change, driven through everything that taught the old model: - Errors keeps the code table and gains the four failures worth triage notes, with 401 pointing at the token rather than at an API key's scopes in Strata Cloud Manager. - The Gateway API introduction gets the counterpart treatment — the request in the first screen, the provider-slug convention named, and a link that escaped into the Portkey-branded docs replaced. - Four worked examples still sent `YOUR_ADMIN_API_KEY`; they now send an access token. - The permissions help-center page routed org-level operations to Admin API keys. It routes them to a token. `mint broken-links` unchanged at 69, none of them in `aigw/api-reference`. Parity guard green at 428 entries. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The spec answers both of the questions the last commit left open, and it
has moved since RESIDUE was written.
There is no single Admin API base URL. Operations carry per-path `servers`
overriding the document root, and they land on two:
`api.apps.paloaltonetworks.com/ai_gw/v2` for configs, workspace guardrails,
providers, API keys, limit policies, MCP servers, analytics and feedback;
`…/ai_gw/admin/v2` for integrations, MCP integrations, secret references,
deployments and organisation guardrails. The split tracks the resource, not
the sidebar group, which is why the introduction now states it as its own
section rather than leaving `$ADMIN_API_BASE_URL` standing in.
Two exceptions are worth a reader's time: the organisation guardrail
endpoints carry `/admin/v2` in the path against an `…/ai_gw` server, and
the two Logs operations are served by the gateway itself at
`aigw.portkey.ai/v1` despite being listed in this tab.
This also corrects the scoping table shipped in the previous commit.
Integrations are organisation-level — they sit on the admin base and are
provisioned *to* workspaces — not workspace-level as it had them.
Every one of the 187 operations now carries `x-mint.href`, so the
generated pages have stable URLs and the introduction deep-links them:
the map, and every step of all five task sequences. Verified by poisoning
one href and confirming `mint broken-links` catches it — it resolves
generated pages, so a silent typo would not have passed.
`enforce-default-config` was calling `POST /admin/api-keys`, which is not
in the spec; it now calls `POST /api-keys/organisation/service` with the
level in the path rather than the body, and its reference card no longer
escapes into the Portkey-branded docs.
Two endpoints used in product prose remain absent from the spec:
`/workspace-exclusions/{direction}-guardrails` and the config-defaults
shape of the API key body. Hosts there are inferred, not verified.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…M steps Rewrite the service account walkthrough against the real Strata Cloud Manager procedure: System Settings > Identity & Access, tenant selection and the inheritance it implies, Identity Type, the Client Credentials screen, the tsg_id on the display name, and Assign Roles. Drop the Gateway API framing from the Admin API introduction, along with the sidebar map and the cross-plane cards, and strip the em dashes from the pages rewritten in this branch. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
…AM details Both pages opened on prose. They now open on a picture: the introduction shows the service account, the token and the two resource levels it reaches, and repeats the scope split as a tree where the organisation and workspace levels are introduced. Authentication gets a sequence diagram of the whole exchange, from creating the account in Strata Cloud Manager to calling an endpoint inside the fifteen-minute window. Checked against the working implementation in prisma-airs-ai-gateway-demo (scm_onboard.py and internal/Claude Code Setup/scm-bulk-assign-role.sh), which has been granting roles on a live tenant since July. The token exchange matched. Four details did not: - The access policy endpoint is api.strata.paloaltonetworks.com/iam/v1, not the api.sase host the older Palo Alto Networks documentation shows. - A policy is three fields with formats worth stating: the PRN, where an empty last segment means the TSG root, and role slugs, where a tenant-defined role carries the tenant ID and a built-in one does not. - The endpoint does not validate the principal. A bogus address returns 201 and leaves a policy that does nothing, verified on the TME tenant in July. That is now a warning. - The token response reports expires_in, so the guidance is to cache for that window rather than to avoid caching. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The flow diagram ran six nodes left to right, about 1800px of natural width against a 1200px column, so Mintlify scaled the whole thing down and the labels came out too small to read. Every diagram on these two pages is now under 950px and renders at full size. - The token flow turns vertical and drops the "your script" node, which cost a column and carried no information. - The scope tree turns horizontal and collapses nine leaf nodes into two, one list per level. - The sequence diagram loses the administrator participant and shortens its messages. - The TSG hierarchy drops its classDef overrides, which fought the theme the other diagrams in the repo inherit. Rendered each one with mermaid-cli to check the dimensions rather than guessing: 517, 684, 950 and 584px wide. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…pe segment
The spec repo dropped the scope segment from the API key create path this
morning (be8e1dc1), an hour before the last commit here. POST
/api-keys/{type}/{sub-type} is now POST /api-keys/{sub-type}, and its docs
URL moved with it.
Their reasoning is that the scope comes from the calling token, so the
segment said twice what the request already carries -- and said it in a
public URL. The same reasoning that removed organisation_id as a parameter.
That makes it a prose correction, not just a link fix. The introduction
told readers the level was a path parameter; it now says the level comes
from the token and sub-type chooses user or service, nothing more. The
worked example in enforce-default-config was calling
/api-keys/organisation/service, which would 404.
docs.json is the sync script's, run with --apply: one group, one operation
added, one removed. mint validate caught the stale nav entry -- it checks
navigation paths against the spec, which is the one drift class the script
was written for.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…on page 84 links across 29 files still resolved to Latest-version routes inherited from the Portkey corpus -- /api-reference/inference-api/responses/responses and the like. They were blocked on having something stable to point at; x-mint.href landed upstream on all 187 operations, so they are not any more. Each was mapped to an operation by method and path, then to that operation's x-mint.href. The mapping is not mechanical -- the old routes were grouped by a navigation tree that no longer exists, so inference-api/models/models is GET /models (list-models), inference-api/responses/responses is POST /responses (create-response), and inference-api/chat is POST /chat/completions. The one link that pointed at a group rather than an operation, in the changelog, now points at the usage limits policy list. Verified three ways: every /aigw/api-reference/ link in the corpus now resolves either to a hand-written page on disk (41) or to a href the spec actually defines (105), no link falls inside a code fence, and mint broken-links reports zero broken links under aigw/. That last check earned its place. A first pass guarded the right edge of the match but not the left, so three links that already carried the /aigw/ prefix came out as /aigw/aigw/... Both validation passes I had written missed it -- they matched the inner substring, which was a legitimate href. broken-links caught all three. They are the same three the tracker listed separately as blocked, so they are now fixed along with the rest. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
product/mcp-gateway/authentication/cas.mdx was deleted in e2021c0, a commit titled "readded steps" that otherwise edited the aigw copy of the same page. The navigation entry stayed behind, so every build since has warned that a page in docs.json does not exist. Removing the entry rather than restoring the file. The page documents CAS authentication for the Strata Cloud Manager MCP Gateway -- Palo Alto console content, which belongs in the Prisma AIRS version and reads oddly in the Portkey-branded Latest docs. Keeping it in aigw/ and dropping it from Latest is coherent; the entry looks like the part that was forgotten. Nothing links to it in either version, so no reader reaches it by any route but the sidebar, and the aigw copy is untouched and still in its nav. This is an edit to the Latest version, which the working agreement puts out of bounds. Made on Vrushank's explicit instruction, the same kind of scoped exception as the Phase 5 webinar banner. If the deletion was the accident and not the nav entry, the fix is `git show 34883ec:product/mcp-gateway/ authentication/cas.mdx` and one line back in docs.json. mint validate is now green with no warnings. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
roh26it
previously approved these changes
Sep 18, 2026
This morning the spec repo dropped the scope segment from the API key create path. sync_api_nav.py caught the navigation and mint validate caught the stale nav entry, but neither can see prose: a sentence calling the level a path parameter, and a worked curl that would now 404, were both found by hand. The check extracts every METHOD /path written under aigw/ and every curl invocation against a gateway host, then asserts each one exists in the published operation list. It reads docs-navigation.json rather than the spec so it needs no YAML parser. curl commands are rejoined across backslash continuations and POST is inferred from body flags, because most examples never pass -X. Two baselines carry what the spec does not: ALLOWED for endpoints outside it by nature, KNOWN_GAPS for endpoints that should be in it. Both may only shrink -- an entry that stops matching anything fails the check too, so a gap that gets fixed upstream cannot sit here unnoticed. Restoring this morning's path makes it exit 1 naming file and line. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Phase 6 flagged one word -- "Behavior" in nitro-mode.mdx -- and guessed there was a class behind it. There was: 107 occurrences across 69 files. Found by parsing each page rather than grepping it, ignoring fenced code, inline code, link targets, JSX attributes and bare URLs, so no functional identifier was ever in range. 96 are behaviour; the remaining 11 are organisation (all on cie-directory-sync.mdx, a page the original sweep seems to have missed outright), cancelling, labelled, labelling, and one Cost Centre. Four classes are deliberately untouched: catalog, because "Model Catalog" is a product name and a route segment; Center, because twelve of thirteen are Microsoft's "M365 Admin Center"; License, a config field in self-hosting; and colors, which is Figma's own vocabulary. -ize/-ise is left alone. The corpus ships "Centralized Control" three lines above "organisation-wide", so which one is correct is a convention decision, not a defect, and it carries a diff of roughly 1,400 words. Five headings changed, so five anchors changed with them. Nothing links to any of them -- checked. The one anchor link that does exist, capabilities.mdx to #guardrail-behavior-on-the-gateway, was already broken before this commit and stays broken; mint broken-links does not see it, because it resolves pages and not anchors. Recorded in TODO. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
mint broken-links resolves a page and ignores the fragment, so a link to a renamed section stays green forever. capabilities.mdx has pointed at #guardrail-behavior-on-the-gateway since Phase 2 renamed that heading to Behaviour. Nothing noticed, because nothing was looking. 66 anchors were broken across 34 targets. 30 are fixed here: - 19 pointed at #there-are-6-types-of-guardrail-actions, from every guardrail integration page. The heading says 7. Someone added an action type and every inbound link broke at once. - 8 were headings renamed without the links following, including extended-thinking-reasoning-models gaining a (Beta) suffix on Bedrock and Vertex but not on Anthropic. - 2 were our own rebrand: #connect-via-portkey-mcp-gateway. - 1 is the behaviour anchor that started this. The remaining 36 are carried in KNOWN with a reason each. They need a destination, not a correction -- the section is gone, not renamed. 24 of them are inherited, absent from the Latest version of the same pages. check_anchors.py compares headings and fragments on letters and digits only. Reimplementing Mintlify's slugifier would invent failures, and a punctuation-only mismatch is invisible to a reader regardless; a word mismatch is where documentation actually breaks. Two notes against rule 3. The guardrail fix was one sed across 19 files, which the rule discourages -- taken because the target was a single provable string, not a judgement per page. The same shortcut then caught me out: a global replace of the extended-thinking anchor also rewrote two Anthropic links that were already correct, and check_anchors.py is what reported it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
whysumedh
approved these changes
Sep 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Admin API requests are authorised with a Strata Cloud Manager access token issued to a service account. A gateway API key returns
401. Nothing in the docs said so, and several worked examples sentYOUR_ADMIN_API_KEY.This branch is the single line of work for the current Prisma AIRS docs updates. Earlier phase branches are merged and have been deleted.
New page: Admin API Authentication
aigw/api-reference/admin-api/authentication.mdx<name>@<tsg_id>.iam.panserviceaccountdisplay name as where the TSG ID comes from, and Assign Roles.https://auth.apps.paloaltonetworks.com/oauth2/access_token, the 15-minute lifespan, and calling an endpoint with the bearer token.tsg_id, and a table of the common failures.Seven
{/* TODO(screenshot): ... */}placeholders mark the UI steps. Those need someone with a tenant.Rewritten: Admin API Introduction
aigw/api-reference/admin-api/introduction.mdxThe old page described two tiers of API key, a permissions model built on who may create them, and workspace and user CRUD that does not exist in the specification. It now opens on what the API manages, walks a first request from the SCM UI through to a call, and then covers the two facts behind most failures: whether a resource is organisation-level or workspace-level, and whether a path takes a slug or an ID. Five common tasks are written as the call sequences they actually are, each deep-linked to its operation page.
The page describes the Admin API only.
Everything that taught the old model
AB05now points at the token rather than at an API key's scopes.@integration/modelconvention named, and a link that escaped into the Latest docs replaced.Checks
mint broken-linksunchanged at 69, none inaigw/api-referencecheck_nav_page_parity.pygreen at 428 entriesmint validateclean apart from one pre-existing warning outsideaigw/🤖 Generated with Claude Code