feat: update MCP quickstart for On-Behalf-Of Token Exchange by lrzhou25 · Pull Request #1052 · auth0/docs-v2

lrzhou25 · 2026-04-27T21:30:27Z

Summary

Updates the "Call Your API on a User's Behalf" MCP quickstart to reflect the new On-Behalf-Of (OBO) Token Exchange implementation, replacing the previous Custom Token Exchange approach.

Changes

JavaScript Updates (based on auth0-samples PR #79)

Sample folder: fastmcp-mcp-customtokenexchange-js → fastmcp-mcp-on-behalf-of-tokenexchange-js
Terminology: "Custom Token Exchange" → "On-Behalf-Of Token Exchange"
Environment variables:
- Removed MCP_AUTH0_SUBJECT_TOKEN_TYPE
- Simplified MCP_AUTH0_EXCHANGE_SCOPE from "openid offline_access read:private" to "read:private"
- Fixed API_BASE_URL trailing slash
Token exchange implementation:
- Function: exchangeCustomToken() → exchangeTokenOnBehalfOf()
- SDK method: getTokenByExchangeProfile() → getTokenOnBehalfOf()
- ApiClient uses AUTH0_AUDIENCE instead of API_AUTH0_AUDIENCE
- Removed subjectTokenType parameter

Python Updates (based on auth0-samples PR #81)

Sample folder: fastmcp-mcp-customtokenexchange-python → fastmcp-mcp-on-behalf-of-tokenexchange-python
Terminology: "Custom Token Exchange" → "On-Behalf-Of Token Exchange"
Token exchange implementation:
- Function: exchange_custom_token() → exchange_token_on_behalf_of()
- SDK method: get_token_by_exchange_profile() → get_token_on_behalf_of()
- ApiClient uses AUTH0_AUDIENCE instead of API_AUTH0_AUDIENCE
- Removed subject_token_type parameter

Additional Improvements

Added rate limit note for Auth0 for AI Agents add-on
Added client grant configuration instructions
Created OBO token exchange enablement component
Updated prerequisites with OBO-specific requirements

Files Changed

mcp/get-started/call-your-apis-on-users-behalf.mdx - Main quickstart page
snippets/mcp/get-started/call-your-apis/create-env-file.mdx - Environment setup
snippets/mcp/get-started/call-your-apis/exchange-access-token-js.mdx - JavaScript explanation
snippets/mcp/get-started/call-your-apis/exchange-access-token-python.mdx - Python explanation
snippets/mcp/get-started/pre-reqs/enable-obo-token-exchange.mdx - New OBO enablement component
snippets/mcp/get-started/pre-reqs/prerequisites.mdx - Updated prerequisites

Testing

Verify JavaScript quickstart instructions work with new sample code
Verify Python quickstart instructions work with new sample code
Verify all code snippets are accurate
Verify links to sample repos are correct
Test OBO token exchange flow end-to-end

🤖 Generated with Claude Code

…n restructuring Migrate internal links across English, French-Canadian (fr-ca), and Japanese (ja-jp) documentation from the old /confidential-and-public-applications/ path structure to the new flattened structure. Updates include: - Move first-party-and-third-party-applications to top-level applications directory - Move user-consent-and-third-party-applications to third-party-applications subdirectory - Move enable-third-party-applications to third-party-applications/configure-third-party-applications - Consolidate view/update application ownership references to first-party applications Files updated: - 55+ documentation files across all three languages - Updated links in markdown content, imports, and cross-references - Preserved anchor links and URL fragments during migration - Updated docs.json with new navigation structure This commit prepares the documentation for the corresponding deletion of old documentation pages under /confidential-and-public-applications/. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…section Add missing pages to French (fr-ca) and Japanese (ja-jp) navigation: - first-party-and-third-party-applications - Third-Party Applications group with all sub-pages - application-access-to-apis-client-grants (fr-ca only) - revoke-api-access This ensures all three language versions have consistent navigation structure. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Create missing translation files to match English navigation structure: French (fr-ca): - first-party-and-third-party-applications.mdx - third-party-applications.mdx + 5 sub-pages - application-access-to-apis-client-grants.mdx - revoke-api-access.mdx Japanese (ja-jp): - first-party-and-third-party-applications.mdx - third-party-applications.mdx + 5 sub-pages - revoke-api-access.mdx Total: 17 new translation files Note: These are copies of English content and will need proper translation by the localization team. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Updates the "Call Your API on a User's Behalf" quickstart to reflect the new On-Behalf-Of (OBO) Token Exchange implementation. JavaScript changes (PR #79): - Update sample folder: fastmcp-mcp-on-behalf-of-tokenexchange-js - Replace Custom Token Exchange with On-Behalf-Of terminology - Simplify environment variables (remove MCP_AUTH0_SUBJECT_TOKEN_TYPE) - Update token exchange: exchangeTokenOnBehalfOf() using getTokenOnBehalfOf() - Simplify MCP_AUTH0_EXCHANGE_SCOPE to "read:private" Python changes (PR #81): - Update sample folder: fastmcp-mcp-on-behalf-of-tokenexchange-python - Replace Custom Token Exchange with On-Behalf-Of terminology - Update token exchange: exchange_token_on_behalf_of() using get_token_on_behalf_of() Additional improvements: - Add rate limit note for Auth0 for AI Agents add-on - Add client grant configuration instructions - Add OBO token exchange enablement component - Update prerequisites with OBO-specific requirements Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

mintlify · 2026-04-27T21:30:55Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
auth0-genai	🟢 Ready	View Preview	Apr 27, 2026, 9:32 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

mintlify · 2026-04-27T21:31:09Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
auth0	🟢 Ready	View Preview	Apr 27, 2026, 9:38 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

github-actions · 2026-04-27T21:31:28Z

Summary

Status	Count
🔍 Total	1015
✅ Successful	134
⏳ Timeouts	0
🔀 Redirected	24
👻 Excluded	844
❓ Unknown	0
🚫 Errors	13
⛔ Unsupported	0

Errors per input

Errors in main/docs/fr-ca/get-started/applications.mdx

[ERROR] https://tools.ietf.org/html/rfc6749#section-2.1 | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

Errors in main/docs/fr-ca/get-started/applications/application-grant-types.mdx

[ERROR] https://tools.ietf.org/html/rfc6749#section-4.5 | Error (cached)

Errors in main/docs/fr-ca/get-started/applications/confidential-and-public-applications.mdx

[ERROR] https://tools.ietf.org/html/rfc6749#section-2.1 | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

Errors in main/docs/get-started/applications.mdx

[ERROR] https://tools.ietf.org/html/rfc6749#section-2.1 | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

Errors in main/docs/ja-jp/get-started/applications.mdx

[ERROR] https://tools.ietf.org/html/rfc6749#section-2.1 | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

Errors in main/docs/ja-jp/get-started/applications/application-grant-types.mdx

[404] https://auth0.com/docs/ja-jp/flows/authorization-code-flow | Rejected status code (this depends on your "accept" configuration): Not Found
[404] https://auth0.com/docs/ja-jp/flows/client-credentials-flow | Rejected status code (this depends on your "accept" configuration): Not Found
[404] https://auth0.com/docs/ja-jp/flows/device-authorization-flow | Rejected status code (this depends on your "accept" configuration): Not Found
[404] https://auth0.com/docs/ja-jp/flows/implicit-flow-with-form-post | Rejected status code (this depends on your "accept" configuration): Not Found
[404] https://auth0.com/docs/ja-jp/flows/resource-owner-password-flow | Rejected status code (this depends on your "accept" configuration): Not Found
[404] https://auth0.com/docs/ja-jp/tokens/refresh-tokens/use-refresh-tokens | Rejected status code (this depends on your "accept" configuration): Not Found
[ERROR] https://tools.ietf.org/html/rfc6749#section-4.5 | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

Errors in main/docs/ja-jp/get-started/applications/confidential-and-public-applications.mdx

[ERROR] https://tools.ietf.org/html/rfc6749#section-2.1 | Cannot find fragment: Fragment not found in document. Check if fragment exists or page structure

Redirects per input

Redirects in auth4genai/mcp/get-started/call-your-apis-on-users-behalf.mdx

[200] https://auth0.com/ai/docs | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://auth0.com/ai/docs --> https://auth0.com/ai/docs/intro/overview

Redirects in main/docs/authenticate/login/oidc-conformant-authentication.mdx

[200] http://openid.net/certification/ | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: http://openid.net/certification/ --> https://openid.net/certification/
[200] http://openid.net/specs/openid-connect-core-1_0.html | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: http://openid.net/specs/openid-connect-core-1_0.html --> https://openid.net/specs/openid-connect-core-1_0.html

Redirects in main/docs/fr-ca/get-started/applications/application-grant-types.mdx

[200] https://auth0.com/docs/flows/authorization-code-flow | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://auth0.com/docs/flows/authorization-code-flow --> https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow
[200] https://auth0.com/docs/flows/client-credentials-flow | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://auth0.com/docs/flows/client-credentials-flow --> https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow
[200] https://auth0.com/docs/flows/device-authorization-flow | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://auth0.com/docs/flows/device-authorization-flow --> https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow
[200] https://auth0.com/docs/flows/implicit-flow-with-form-post | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://auth0.com/docs/flows/implicit-flow-with-form-post --> https://auth0.com/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post
[200] https://auth0.com/docs/flows/resource-owner-password-flow | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://auth0.com/docs/flows/resource-owner-password-flow --> https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow
[200] https://auth0.com/docs/tokens/refresh-tokens/use-refresh-tokens | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://auth0.com/docs/tokens/refresh-tokens/use-refresh-tokens --> https://auth0.com/docs/secure/tokens/refresh-tokens/use-refresh-tokens

Redirects in main/docs/fr-ca/get-started/applications/application-settings.mdx

[200] https://www.owasp.org/index.php/Unvalidated_Redirects_and_Forwards_Cheat_Sheet | Redirect: Followed 2 redirects resolving to the final status of: OK. Redirects: https://www.owasp.org/index.php/Unvalidated_Redirects_and_Forwards_Cheat_Sheet --> https://owasp.org/index.php/Unvalidated_Redirects_and_Forwards_Cheat_Sheet --> https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html

Redirects in main/docs/fr-ca/get-started/applications/first-party-and-third-party-applications.mdx

[200] https://auth0.com/docs/api/management/v2/tokens | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://auth0.com/docs/api/management/v2/tokens --> https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens

Redirects in main/docs/fr-ca/libraries/auth0-single-page-app-sdk.mdx

[200] https://github.com/auth0/auth0-spa-js/blob/master/FAQ.md | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://github.com/auth0/auth0-spa-js/blob/master/FAQ.md --> https://github.com/auth0/auth0-spa-js/blob/main/FAQ.md

Redirects in main/docs/fr-ca/libraries/auth0js.mdx

[200] http://nodejs.org/ | Redirect: Followed 2 redirects resolving to the final status of: OK. Redirects: http://nodejs.org/ --> https://nodejs.org/ --> https://nodejs.org/en

Redirects in main/docs/fr-ca/libraries/lock.mdx

[200] http://bower.io/ | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: http://bower.io/ --> https://bower.io/
[200] https://npmjs.org/ | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://npmjs.org/ --> https://www.npmjs.com/

Redirects in main/docs/fr-ca/secure/tokens/json-web-tokens/json-web-token-claims.mdx

[200] https://tools.ietf.org/html/rfc7519 | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://tools.ietf.org/html/rfc7519 --> https://datatracker.ietf.org/doc/html/rfc7519

Redirects in main/docs/fr-ca/secure/tokens/refresh-tokens/multi-resource-refresh-token.mdx

[200] https://www.okta.com/legal | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://www.okta.com/legal --> https://www.okta.com/legal/

Redirects in main/docs/ja-jp/get-started/applications/application-settings.mdx

[200] https://www.owasp.org/index.php/Unvalidated_Redirects_and_Forwards_Cheat_Sheet | Redirect: Followed 2 redirects resolving to the final status of: OK. Redirects: https://www.owasp.org/index.php/Unvalidated_Redirects_and_Forwards_Cheat_Sheet --> https://owasp.org/index.php/Unvalidated_Redirects_and_Forwards_Cheat_Sheet --> https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html

Redirects in main/docs/ja-jp/get-started/applications/first-party-and-third-party-applications.mdx

[200] https://auth0.com/docs/api/management/v2/tokens | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://auth0.com/docs/api/management/v2/tokens --> https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens

Redirects in main/docs/ja-jp/libraries/auth0-single-page-app-sdk.mdx

[200] https://github.com/auth0/auth0-spa-js/blob/master/FAQ.md | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://github.com/auth0/auth0-spa-js/blob/master/FAQ.md --> https://github.com/auth0/auth0-spa-js/blob/main/FAQ.md

Redirects in main/docs/ja-jp/secure/tokens/refresh-tokens/multi-resource-refresh-token.mdx

[200] https://www.okta.com/legal | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://www.okta.com/legal --> https://www.okta.com/legal/

Redirects in main/docs/libraries/auth0-single-page-app-sdk.mdx

[200] https://github.com/auth0/auth0-spa-js/blob/master/FAQ.md | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://github.com/auth0/auth0-spa-js/blob/master/FAQ.md --> https://github.com/auth0/auth0-spa-js/blob/main/FAQ.md
[200] https://npmjs.org/ | Redirect: Followed 1 redirect resolving to the final status of: OK. Redirects: https://npmjs.org/ --> https://www.npmjs.com/

Redirects in main/docs/libraries/auth0js.mdx

[200] http://nodejs.org/ | Redirect: Followed 2 redirects resolving to the final status of: OK. Redirects: http://nodejs.org/ --> https://nodejs.org/ --> https://nodejs.org/en
Full Github Actions output

lrzhou25 · 2026-04-27T21:33:18Z

Closing this PR - created a clean version without unrelated changes from 3p_redirects branch. See new PR.

lrzhou25 and others added 4 commits April 27, 2026 12:17

lrzhou25 requested review from a team as code owners April 27, 2026 21:30

mintlify Bot deployed to staging - auth4genai April 27, 2026 21:32 View deployment

lrzhou25 closed this Apr 27, 2026

mintlify Bot deployed to staging - main April 27, 2026 21:38 View deployment

hazel-nut deleted the auth_for_mcp_ga_docs branch May 1, 2026 17:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: update MCP quickstart for On-Behalf-Of Token Exchange#1052

feat: update MCP quickstart for On-Behalf-Of Token Exchange#1052
lrzhou25 wants to merge 4 commits into
mainfrom
auth_for_mcp_ga_docs

lrzhou25 commented Apr 27, 2026

Uh oh!

mintlify Bot commented Apr 27, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Apr 27, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 27, 2026

Uh oh!

lrzhou25 commented Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

lrzhou25 commented Apr 27, 2026

Summary

Changes

JavaScript Updates (based on auth0-samples PR #79)

Python Updates (based on auth0-samples PR #81)

Additional Improvements

Files Changed

Testing

Uh oh!

mintlify Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mintlify Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 27, 2026

Summary

Errors per input

Errors in main/docs/fr-ca/get-started/applications.mdx

Errors in main/docs/fr-ca/get-started/applications/application-grant-types.mdx

Errors in main/docs/fr-ca/get-started/applications/confidential-and-public-applications.mdx

Errors in main/docs/get-started/applications.mdx

Errors in main/docs/ja-jp/get-started/applications.mdx

Errors in main/docs/ja-jp/get-started/applications/application-grant-types.mdx

Errors in main/docs/ja-jp/get-started/applications/confidential-and-public-applications.mdx

Redirects per input

Redirects in auth4genai/mcp/get-started/call-your-apis-on-users-behalf.mdx

Redirects in main/docs/authenticate/login/oidc-conformant-authentication.mdx

Redirects in main/docs/fr-ca/get-started/applications/application-grant-types.mdx

Redirects in main/docs/fr-ca/get-started/applications/application-settings.mdx

Redirects in main/docs/fr-ca/get-started/applications/first-party-and-third-party-applications.mdx

Redirects in main/docs/fr-ca/libraries/auth0-single-page-app-sdk.mdx

Redirects in main/docs/fr-ca/libraries/auth0js.mdx

Redirects in main/docs/fr-ca/libraries/lock.mdx

Redirects in main/docs/fr-ca/secure/tokens/json-web-tokens/json-web-token-claims.mdx

Redirects in main/docs/fr-ca/secure/tokens/refresh-tokens/multi-resource-refresh-token.mdx

Redirects in main/docs/ja-jp/get-started/applications/application-settings.mdx

Redirects in main/docs/ja-jp/get-started/applications/first-party-and-third-party-applications.mdx

Redirects in main/docs/ja-jp/libraries/auth0-single-page-app-sdk.mdx

Redirects in main/docs/ja-jp/secure/tokens/refresh-tokens/multi-resource-refresh-token.mdx

Redirects in main/docs/libraries/auth0-single-page-app-sdk.mdx

Redirects in main/docs/libraries/auth0js.mdx

Uh oh!

lrzhou25 commented Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mintlify Bot commented Apr 27, 2026 •

edited

Loading

mintlify Bot commented Apr 27, 2026 •

edited

Loading