OKTA-1222987 - Register AI agents with CIMD - #6302
Merged
vanngo-okta merged 20 commits intoJul 29, 2026
Merged
Conversation
Adds the ai-agent-cimd-registration guide (primer, registration task, Admin Console UI-gap callout, token request, troubleshooting) as a single devdocs topic file, plus a hidden Okta for AI Agents nav section and Google disallow entry per the Beta/LEA hiding process. Several sections are flagged inline pending live-org verification, legal sign-off, and the Agent Gateway concept doc merge.
brentschaus-okta
requested review from
barbaravo-okta,
emikhasyak-okta,
grahamsmith-okta,
ishan-krishna-okta,
janethu-okta,
paulwallace-okta and
susanharper-okta
as code owners
July 13, 2026 20:21
…em/en dashes Split sentences over 25 words, added length variety to paragraphs that had only same-length sentences, and rewrote around em/en dashes.
Rewrites four passive constructions (is set, can't be changed, is required x2, is expected) plus two participial requirement bullets into active phrasing.
Repo convention names the human-readable feature and its enablement path, not the internal flag constant (see ea-ai-agent-token-exchange). Move CIMD_CLIENT_METADATA_DOCUMENT/AI_AGENT_CIMD_REGISTRATION into a draft comment pending confirmation of the console feature name.
Removes two internal-review draft comments now resolved by the Overview and metadata-requirements sections. Replaces the two placeholder link TODOs with the actual IETF Internet-Draft and client.dev CIMD resources.
…dmin Console note Removes three more internal-review draft comments now resolved. Drops the Admin Console subheading and moves its note ahead of the exact-match callout within the registration section, and trims a redundant sentence from that note.
…e API Live-tested against a QA org: the documented request body (displayName) returns a 400 (real field is profile.name/description), and registration is async (202 + Location header to an operation), not the synchronous 200 + full-body response the guide showed. Also corrected the example response shape and softened the troubleshooting table's HTTPS-enforcement claim, which isn't actually enforced at registration time (flagged as a DRAFT for engineering follow-up).
…rom eng thread Engineering confirmed in the #cimd-okta-secures-ai thread: CIMD clients use private_key_jwt with the token-exchange and jwt-bearer grant types (not client_credentials), and Okta validates client_id, jwks_uri, and redirect_uris in the hosted CIMD document. Adds the missing token-request code sample and corrects the metadata-document-requirements claim that Okta doesn't define required fields. Also reverts the HTTPS-validation troubleshooting note back to its original wording: the lax http:// acceptance seen during live testing was an artifact of testing against a dev-tier org (serverDetails.isDev()), not a real gap — confirmed via OKTA-1223871, closed as not a bug. Sets the lifecycle tag to Research Release per PM guidance, replacing the open EA-designation question.
Match the PR 6299 pattern: keep the CIMD registration guide out of the navbar structure and surface it only via docs/guides/index.md.
Tightens wording throughout, resolves the ambiguous "agent operator" term with a clarifying parenthetical, and rewrites the BYOK-to-CIMD migration note to say plainly that the existing AI agent record must be deleted and recreated.
barbaravo-okta
previously approved these changes
Jul 28, 2026
Links to the Agent Gateway concept doc and the AI agent registration OAS3 reference, in addition to the already-verified CIMD spec links.
Verified against atko-eng/okta-oas3 PR #3577 (Tian Gan), which added CIMD registration to the AgentRegistration tag in the secures-ai-workload-principals spec. The tag slug is agentregistration, not the guessed aiagents.
Confirmed against atko-eng/okta-core PR #130112 (OKTA-1168174, merged, no feature flag gate): the 7-day/2-day-idle default applies based solely on ClientType.CIMD, with no AI-agent-specific carve-out, so it applies identically to AI-agent CIMD registrations.
Ties the new CIMD refresh token lifetime fact (7-day/2-day idle) to a concrete troubleshooting symptom, so an expired refresh token doesn't read as an unexplained bug.
The specific numbers now live only in the Refresh token lifetime section; the troubleshooting row just names the symptom and links there instead of restating them.
Contributor
Author
|
Build failure investigated: the internal link checker flags Merge-order requirement: merge #6290 before this PR (or rebase this branch on top of it) so the link resolves and the build check passes. |
…ation/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com>
Acrolinx scoreA minimum Acrolinx Score of 80 is required. The total score is an average of the subscores.
Successfully checked 3 of 3 documents. Reopen the pull request or push new changes to check again. Depending on the Acrolinx server configuration, the |
barbaravo-okta
approved these changes
Jul 28, 2026
brentschaus-okta
added
the
docs release
The concept page doesn't exist on release-2026.07.3 yet, which broke the link checker build.
vanngo-okta
added a commit
that referenced
this pull request
Jul 30, 2026
* Agent gateway configure agent guide (#6287) * configure agent for gateway * initial edits * edits round 2 * restructure of example code section * CIMD clarification * link comments * flow diagram link and mcp feature enablement requirement * Add research badge and link * Add remainder of links * Add doc to guides index, reviewed with ai editing and acrolinx * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-for-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> --------- Co-authored-by: Brian Duffield <brian.duffield@okta.com> Co-authored-by: Brian Duffield - Okta <70648001+brianduffield-okta@users.noreply.github.com> Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Agent Gateway concept (#6290) * first round of edits * forgot to save * agent gateway concept * Brian comment and mcp gateway team comments * clarify oauth 2.0 * antoine, kishan, mohamed review comments * adding row in limitations table per Kishan about REST API and GraphQL APIs * Add research badge and links * Updates as per AI edit * Add three agent gateway guides to disallow * Minor update as per alias discussion * Add flow image * Reposition badge * Apply suggestions from code review Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Add review comment from line 16 --------- Co-authored-by: Brian Duffield <brian.duffield@okta.com> Co-authored-by: Brian Duffield - Okta <70648001+brianduffield-okta@users.noreply.github.com> Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Configure Agent Gateway using the APIs (#6299) * stubbing out new guide * tweak * more edits * what you need * claude cross checking APIs vs github UI code for agent gateway * updates and edits * acrolinx * Add additonal request response headers * Updates to use Agent Gateway instead of vMCP where appropriate - as per feedback * removed section on linking to the custom auth server and any references to this task -- as per feedback * Add new section on retrieve the virtual mcp settings * Minor update to learning outcomes * Add doc to guides index and add research badge * Updates as per ai editing and acrolinx * add link * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Update packages/@okta/vuepress-site/docs/guides/ai-configure-agent-gateway/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Add bit in Overview from editing review --------- Co-authored-by: Brian Duffield <brian.duffield@okta.com> Co-authored-by: Brian Duffield - Okta <70648001+brianduffield-okta@users.noreply.github.com> Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Add phr claim (#6322) * Add phr claim * SME update * Other file * OKTA-1082825 RN entries for 2026.07.3 (#6341) * Add rn entries for 2026.07.3 - still draft * Add table row * Clean up RN entry list * Update bug RN based on Brian's feedback * Update packages/@okta/vuepress-site/docs/release-notes/2026-okta-identity-engine/index.md Co-authored-by: janugeethakumari-okta <janu.geethakumari@okta.com> --------- Co-authored-by: janugeethakumari-okta <janu.geethakumari@okta.com> * OKTA-1222987 - Register AI agents with CIMD (#6302) * OKTA-1222987 - Add draft guide for registering AI agents with CIMD Adds the ai-agent-cimd-registration guide (primer, registration task, Admin Console UI-gap callout, token request, troubleshooting) as a single devdocs topic file, plus a hidden Okta for AI Agents nav section and Google disallow entry per the Beta/LEA hiding process. Several sections are flagged inline pending live-org verification, legal sign-off, and the Agent Gateway concept doc merge. * acrolinx review * OKTA-1222987 - Tighten sentence length, vary sentence rhythm, remove em/en dashes Split sentences over 25 words, added length variety to paragraphs that had only same-length sentences, and rewrote around em/en dashes. * OKTA-1222987 - Convert passive voice to active in CIMD guide Rewrites four passive constructions (is set, can't be changed, is required x2, is expected) plus two participial requirement bullets into active phrasing. * OKTA-1222987 - Stop naming raw feature flags in CIMD guide prose Repo convention names the human-readable feature and its enablement path, not the internal flag constant (see ea-ai-agent-token-exchange). Move CIMD_CLIENT_METADATA_DOCUMENT/AI_AGENT_CIMD_REGISTRATION into a draft comment pending confirmation of the console feature name. * OKTA-1222987 - Clear resolved draft comments, add CIMD spec links Removes two internal-review draft comments now resolved by the Overview and metadata-requirements sections. Replaces the two placeholder link TODOs with the actual IETF Internet-Draft and client.dev CIMD resources. * OKTA-1222987 - Clear remaining resolved draft comments, restructure Admin Console note Removes three more internal-review draft comments now resolved. Drops the Admin Console subheading and moves its note ahead of the exact-match callout within the registration section, and trims a redundant sentence from that note. * more acrolinx * OKTA-1222987 - Fix registration request/response contract against live API Live-tested against a QA org: the documented request body (displayName) returns a 400 (real field is profile.name/description), and registration is async (202 + Location header to an operation), not the synchronous 200 + full-body response the guide showed. Also corrected the example response shape and softened the troubleshooting table's HTTPS-enforcement claim, which isn't actually enforced at registration time (flagged as a DRAFT for engineering follow-up). * OKTA-1222987 - Fill in token-request flow and CIMD doc requirements from eng thread Engineering confirmed in the #cimd-okta-secures-ai thread: CIMD clients use private_key_jwt with the token-exchange and jwt-bearer grant types (not client_credentials), and Okta validates client_id, jwks_uri, and redirect_uris in the hosted CIMD document. Adds the missing token-request code sample and corrects the metadata-document-requirements claim that Okta doesn't define required fields. Also reverts the HTTPS-validation troubleshooting note back to its original wording: the lax http:// acceptance seen during live testing was an artifact of testing against a dev-tier org (serverDetails.isDev()), not a real gap — confirmed via OKTA-1223871, closed as not a bug. Sets the lifecycle tag to Research Release per PM guidance, replacing the open EA-designation question. * Remove hidden nav section, list guide in guides index instead Match the PR 6299 pattern: keep the CIMD registration guide out of the navbar structure and surface it only via docs/guides/index.md. * Apply Barbara Vo's editorial feedback on CIMD registration guide Tightens wording throughout, resolves the ambiguous "agent operator" term with a clarifying parenthetical, and rewrites the BYOK-to-CIMD migration note to say plainly that the existing AI agent record must be deleted and recreated. * Remove draft comments and add links in See also section Links to the Agent Gateway concept doc and the AI agent registration OAS3 reference, in addition to the already-verified CIMD spec links. * Correct OAS3 tag slug for Register an AI agent link Verified against atko-eng/okta-oas3 PR #3577 (Tian Gan), which added CIMD registration to the AgentRegistration tag in the secures-ai-workload-principals spec. The tag slug is agentregistration, not the guessed aiagents. * Resolve draft comment on refresh token lifetime for CIMD clients Confirmed against atko-eng/okta-core PR #130112 (OKTA-1168174, merged, no feature flag gate): the 7-day/2-day-idle default applies based solely on ClientType.CIMD, with no AI-agent-specific carve-out, so it applies identically to AI-agent CIMD registrations. * Add refresh token expiry row to token request troubleshooting table Ties the new CIMD refresh token lifetime fact (7-day/2-day idle) to a concrete troubleshooting symptom, so an expired refresh token doesn't read as an unexplained bug. * Deduplicate refresh token lifetime details in troubleshooting table The specific numbers now live only in the Refresh token lifetime section; the troubleshooting row just names the symptom and links there instead of restating them. * Update packages/@okta/vuepress-site/docs/guides/ai-agent-cimd-registration/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Comment out Agent Gateway link until PR #6290 merges The concept page doesn't exist on release-2026.07.3 yet, which broke the link checker build. --------- Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: brentschaus-okta <89146940+brentschaus-okta@users.noreply.github.com> * Remove broken link in ai-configure-agent-gateway * Update RSS files * Add doc action for 7.0 --------- Co-authored-by: Susan <susan.harper@okta.com> Co-authored-by: Brian Duffield <brian.duffield@okta.com> Co-authored-by: Brian Duffield - Okta <70648001+brianduffield-okta@users.noreply.github.com> Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com> Co-authored-by: thomascavanagh-okta <thomas.cavanagh@okta.com> Co-authored-by: janugeethakumari-okta <janu.geethakumari@okta.com> Co-authored-by: brentschaus-okta <89146940+brentschaus-okta@users.noreply.github.com>
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.
Description:
What's changed? Adds a draft guide for registering AI agents with a Client ID Metadata Document (CIMD) OAuth client, instead of a static client ID or BYOK public key. Covers the CIMD primer, the registration API call, the Admin Console UI gap (CIMD registrations don't show up in the Credentials tab yet), using the CIMD client ID in a token request, and troubleshooting.
Is this PR related to a Monolith release? Yes. 2026.07.3
Resolves:
Vercel Preview Link:
Preview link