[TT-15552] docs: add Direct Access Flow & Existing Credential Multiple API Products guide for Developer Portal

[buger]

Summary

• Rewrite the Direct Access Flow documentation as a step-by-step guide following the standard how-to guide format
• Structure aligns with the reference guide at import-custom-credentials
• Removed feature explanation sections, focusing on actionable instructions

Changes

The revised guide (portal/direct-access-flow.mdx) now follows the standard format:

1. Availability - Version and edition requirements (v1.16+, Enterprise)
2. Prerequisites - Numbered list of required setup
3. What we will do - Numbered summary of tasks
4. Instructions - Step-by-step numbered guide:
   • Step 1: Enable Direct Access Flow (Admin)
   • Step 2: Request Access to an API Product (Developer)
   • Step 3: Add More Products Using an Existing Credential
   • Step 4: Change the Plan for an Existing Credential
   • Step 5: Handle Different Plans Within the Same Application
   • Step 6: Configure Access as an Admin
   • Step 7: Revert to Cart-based Flow (Optional)

Key Changes from Previous Version

• Removed Introduction section (was feature explanation)
• Removed Comparison table (moved key info to relevant steps)
• Removed Troubleshooting section (not part of step-by-step format)
• Removed Best Practices section (not part of step-by-step format)
• Restructured all content as numbered actionable instructions
• Added appropriate <Note> and <Warning> callouts where needed

Related Issues

Resolves TT-15552 - Simplify the access management flow by allowing users to turn off the shopping cart flow

Test Plan

• Verify markdown renders correctly on the documentation site
• Confirm all internal links work
• Verify structure matches the reference guide format
• Check navigation includes the new page under "Consuming APIs"

🤖 Generated with Claude Code

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Terminology Consistency The document alternates between "Portal administrators", "API Owner", and "administrator". Consider standardizing roles/titles and clarifying who approves requests to avoid confusion for readers. Portal administrators can enable the Direct Access flow through the admin portal settings: 1. Log in to the Admin Portal as an administrator 2. Navigate to **Settings** in the main navigation 3. Select **General** from the settings menu 4. Locate the **API product access flow** setting 5. Switch the option from **Cart-based flow** to **Direct access flow** 6. Select **Save** to apply the changes Once enabled, all API consumers will experience the streamlined Direct Access flow when requesting access to API products. ## Developer Experience with Direct Access Flow ### Requesting Access to Your First Product When the Direct Access flow is enabled, developers can request access to an API product with minimal steps: 1. Browse the API Catalog and select an API product 2. Review the available plans and select your preferred plan 3. Select **Request access** (or equivalent button based on your portal theme) 4. You will be taken directly to the access request page 5. Enter an **Application name** for your new application - Optionally add a description and configure visibility settings 6. Select **Submit request** Your access request will be submitted for approval. If the plan is configured for auto-approval, credentials will be issued immediately. Otherwise, an API Owner will review and approve your request. ### Adding More Products to an Existing Application Once you have an application with approved access to at least one API product, you can add access to additional products: 1. Browse the API Catalog and select another API product 2. Select your preferred plan for this product 3. Select **Request access** 4. On the access request page, you have two options: - **Use existing credential**: Select an existing application and credential to associate with this new product access - **Create new credential**: Generate a new credential specifically for this product 5. Select **Submit request** <Note> When choosing to use an existing credential, the system will only show credentials that are compatible with your selected plan. See [Credential Compatibility Rules](/portal/direct-access-flow#credential-compatibility-rules) for details. </Note> ### Changing API Plans Developers can upgrade or downgrade their plan for an existing product access: 1. Navigate to **My Dashboard** from the user menu 2. Go to **My Apps** and select the relevant application 3. Find the API product access you want to modify 4. Select **Change plan** or the equivalent option 5. Choose your new plan (upgrade or downgrade) 6. Submit the plan change request **Important behavior:** - A plan change creates a **new pending request** that requires approval (unless auto-approved) - Your **existing access remains active** on the current plan until the new plan is approved - Once approved, your access will be updated to the new plan - This ensures uninterrupted API access during the plan change process ## Credential Compatibility Rules A key concept when using the Direct Access flow is understanding credential compatibility: **A single credential can only be associated with ONE API plan.** This means if you have an existing credential that provides access to products on a specific plan (e.g., "Platinum"), you cannot reuse that same credential to request access to a product on a different plan (e.g., "Bronze"). ### Example Scenario Consider a developer named Alex who has the following setup: 1. Alex has an application called "My Weather App" 2. This application has a credential providing access to: - Weather API on the **Platinum** plan - Maps API on the **Platinum** plan Now Alex wants to add access to the Notifications API: - **If selecting the Platinum plan**: Alex can reuse the existing credential - **If selecting the Bronze plan**: Alex must create a new credential, as the existing one is already associated with the Platinum plan This design ensures consistent rate limiting and quota enforcement across all products accessed through a single credential. ### Best Practices - Group API products that you need to access together under the same plan when possible - Plan your credential strategy based on your rate limit and quota requirements - Create separate applications for products that require different plans ## Backward Compatibility The Direct Access flow feature is fully backward compatible: - **Optional enablement**: The Cart-based flow remains the default. Organizations only switch to Direct Access flow when it suits their business model. - **Easy rollback**: Administrators can switch back to the Cart-based flow at any time by: 1. Navigating to **Settings > General** 2. Changing the **API product access flow** setting back to **Cart-based flow** 3. Saving the changes - **No data migration**: Switching between flows does not affect existing applications, credentials, or access approvals. Developers retain all their current access. - **Existing integrations**: Any existing developer applications and access credentials continue to work regardless of which flow is enabled. ## Comparison: Cart-based vs Direct Access Flow | Aspect | Cart-based Flow | Direct Access Flow | |--------|-----------------|-------------------| | Shopping cart | Yes | No | | Steps to request access | More (add to cart, checkout, submit) | Fewer (select, submit) | | Best for | Monetized APIs, complex subscriptions | Indirect monetization, streamlined onboarding | | Multiple products at once | Yes (via cart) | One product per request | | User experience | E-commerce style | Streamlined, minimal friction | ## Troubleshooting ### Cannot Reuse Existing Credential If you cannot select an existing credential when requesting access: - Verify the credential's associated plan matches your selected plan - Check that the credential belongs to an application you own - Ensure the application is not in a pending or suspended state ### Plan Change Not Reflected If your plan change doesn't appear to take effect: - Check if the plan change request is still pending approval - Contact your API Owner or portal administrator to review the request status - Your current access remains active until the new plan is approved ### Access Request Stuck in Pending If your access request remains pending: - Verify the plan is not configured for manual approval - Contact your API Owner or organization administrator Internal Link Check The self-reference link to the "Credential Compatibility Rules" section should be verified for correct anchor generation in the site (slug/heading IDs may differ). Ensure the link resolves after build. <Note> When choosing to use an existing credential, the system will only show credentials that are compatible with your selected plan. See [Credential Compatibility Rules](/portal/direct-access-flow#credential-compatibility-rules) for details. </Note> Navigation Placement Confirm that adding "portal/direct-access-flow" under "Consuming APIs" is the intended taxonomy and that sidebar ordering is correct relative to adjacent pages. "group": "Consuming APIs", "pages": [ "portal/developer-app", "portal/direct-access-flow", "tyk-stack/tyk-developer-portal/enterprise-developer-portal/api-access/approve-requests", { "group": "Guides", "pages": [

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Make link path relative Use a relative link without a leading slash to avoid breaking links when the site is hosted under a subpath. This ensures the anchor works in all deployment contexts. portal/direct-access-flow.mdx [65] -See [Credential Compatibility Rules](/portal/direct-access-flow#credential-compatibility-rules) for details. +See [Credential Compatibility Rules](./direct-access-flow#credential-compatibility-rules) for details. Suggestion importance[1-10]: 5 __ Why: Using a relative link can help when the site is served under a subpath, but many doc systems handle absolute links correctly. The change is reasonable yet context-dependent.	Low
	Use supported admonition syntax Confirm the admonition component name matches your docs system (e.g., Note vs. note or using :::note). If the system uses MDX components, import or use the supported syntax to prevent render failures. portal/direct-access-flow.mdx [18-20] -<Note> +:::note The Direct Access flow is optional. Portal administrators can switch between access flows at any time based on their business requirements. -</Note> +::: Suggestion importance[1-10]: 4 __ Why: Admonition syntax varies by docs setup; replacing <Note> with :::note might help if MDX components aren't configured, but it's speculative without evidence of the current system, so impact is limited.	Low
Possible issue	Fix page path mismatch Ensure the new page slug matches the actual file path so links resolve correctly. If your docs system requires an extensionless path, confirm routing; otherwise, use the correct relative path to the MDX file. docs.json [509-512] "portal/developer-app", -"portal/direct-access-flow", +"portal/direct-access-flow.mdx", "tyk-stack/tyk-developer-portal/enterprise-developer-portal/api-access/approve-requests", Suggestion importance[1-10]: 3 __ Why: The JSON nav typically lists slugs without file extensions; changing to .mdx may break routing. The suggestion asks to "ensure/confirm" rather than asserting a necessary change, so impact is minor and uncertain.	Low

[caroltyk]

LGTM