Clarify auth flows #15
Conversation
|
ℹ️ API content change detected: No structural change, nothing to display.
|
| @@ -24,17 +24,27 @@ If you successfully retrieve an access token, it is valid for one hour. You can | |||
|
|
|||
| ### BYOC or Dedicated | |||
|
|
|||
| 1. In the page header, click **API Explorer**. | |||
There was a problem hiding this comment.
Above, add links to Cloud API Overview and Data Plane API Reference.
There was a problem hiding this comment.
Also, the link in the quickstart to Redpanda HTTP Proxy doesn't work
There was a problem hiding this comment.
Link to Serverless trial does not work. You could use https://www.redpanda.com/try-redpanda
There was a problem hiding this comment.
Several links in Cloud API Overview not working. Also, we should be consistent with links (See ... vs See also with a bulleted item)
There was a problem hiding this comment.
In quickstart/Cloud API Overview, the deprecation lines are not formatting correctly in the Important notes, and seem a little redundant with the Versioning and deprecation section below them.
There was a problem hiding this comment.
For the note, I think it might be something to do with how the Markdown is processed. I'll make a note and raise with the Bump team.
| When using the API Explorer in your browser, Redpanda Cloud uses the [OAuth 2.0 Implicit Flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.2): | ||
|
|
||
| 1. Click **Get token** on any API endpoint. | ||
| 2. Log in with your Redpanda Cloud credentials if prompted. After you log in, you are redirected back to the API Explorer. |
There was a problem hiding this comment.
| 2. Log in with your Redpanda Cloud credentials if prompted. After you log in, you are redirected back to the API Explorer. | |
| 2. Log in with your Redpanda Cloud credentials, if prompted. After you log in, you are redirected back to the API Explorer. |
cloud-dataplane/cloud-dataplane.yaml
Outdated
| Example (Dedicated): "https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com"<br> | ||
| Example (BYOC): "https://api-a4cb21.ck09mi9c4vs17hng9gig.byoc.prd.cloud.redpanda.com" |
There was a problem hiding this comment.
I think we should always put BYOC before Dedicated
There was a problem hiding this comment.
This is lifted from the source in cloudv2, but we can change it here and then backport.
| @@ -24,17 +24,27 @@ If you successfully retrieve an access token, it is valid for one hour. You can | |||
|
|
|||
| ### BYOC or Dedicated | |||
|
|
|||
| 1. In the page header, click **API Explorer**. | |||
| 1. Open **API Explorer**. | |||
There was a problem hiding this comment.
I think this quickstart needs to introduce the API Explorer a little better
There was a problem hiding this comment.
Does the current API docs say, "Reach out to support."? I think it's better to say, "Contact Support." Or maybe more info, or a link. I'm not sure how prevalent it is in the API docs.
There was a problem hiding this comment.
Yes, there are doc team conventions that haven't yet been adopted by the Engineering org as guidelines or styles in writing API descriptions or docs in general. It's a larger conversation to be had and will require effort to enforce. I think if we can encourage ENG to use our docs MCP server, that might help.
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis PR updates Redpanda Cloud documentation and OpenAPI specs:
Sequence Diagram(s)sequenceDiagram
participant User
participant API_Explorer
participant ControlPlaneAPI as Control Plane API
participant DataPlaneAPI as Data Plane API
User->>API_Explorer: Open Control/Dataplane docs
API_Explorer-->>User: Prompt to authenticate (browser flow)
User->>API_Explorer: Authenticate
API_Explorer->>ControlPlaneAPI: Get Cluster (retrieve dataplane_api.url)
ControlPlaneAPI-->>API_Explorer: dataplane_api.url
API_Explorer->>API_Explorer: Derive subdomain (overlay variable)
API_Explorer->>DataPlaneAPI: Send request using base URL
DataPlaneAPI-->>API_Explorer: Response
sequenceDiagram
participant Client
participant OAuth as OAuth Token Endpoint
participant CP as Control Plane API
participant DP as Data Plane API
Client->>OAuth: POST /oauth/token (client_credentials)
OAuth-->>Client: access_token (1 hour)
Client->>CP: API request with Authorization: Bearer <token>
CP-->>Client: Response
Client->>DP: API request with Authorization: Bearer <token>
DP-->>Client: Response
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes ✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
♻️ Duplicate comments (2)
shared/overlays/update-securityschemes-for-authentication.yaml (1)
15-15: Link directly to the Authentication topic.Add a working cross-reference to help users find the detailed steps.
- **For programmatic access (CLI, SDKs, scripts):** You must create a service account in the Redpanda Cloud UI and use the OAuth 2.0 client credentials flow to obtain an access token. See the Authentication topic for detailed instructions. + **For programmatic access (CLI, SDKs, scripts):** You must create a service account in the Redpanda Cloud UI and use the OAuth 2.0 client credentials flow to obtain an access token. See the [Authentication](#topic-about-authentication) topic for detailed instructions.cloud-dataplane/overlays/update-dataplane-server-config.yaml (1)
16-21: Great clarity on how to extract and enter the subdomain.
The example now directly shows the input format users must provide, which reduces confusion.
🧹 Nitpick comments (13)
shared/x-topics/about-authentication.md (5)
3-3: Clarify scope of “authenticate once.”“Authenticate once” can be misread as indefinite. Suggest making the token validity window explicit.
-You only need to authenticate once to the Cloud API. That is, after you obtain an access token, you can use the same token in requests to both Control Plane and Data Plane API endpoints, for as long as the token is valid. +You only need to authenticate once per token validity period. After you obtain an access token, you can use the same token in requests to both Control Plane and Data Plane API endpoints while the token remains valid.
9-12: Constrain “automatically applied” to API Explorer context.Minor wording to avoid implying automatic token application outside API Explorer.
-3. The token is automatically applied to your API requests. +3. Within API Explorer, the token is automatically applied to your API requests.
33-39: Standardize HTTP header casing.Use the conventional header casing for Content-Type.
- -H "content-type: application/x-www-form-urlencoded" \ + -H "Content-Type: application/x-www-form-urlencoded" \
25-26: Confirm service account privilege statement.“Service accounts have administrative privileges by default. Cloud user roles are not applied for the API.” This has security implications. Please confirm this is current behavior and intended for public docs.
If needed, I can propose a short “Least privilege” note and link to role-scoping guidance once available.
47-51: Match the tip with the example by quoting the header.Your tip recommends double quotes; mirror it in the example for consistency.
-curl -H "Authorization: Bearer $YOUR_TOKEN" +curl -H "Authorization: Bearer $YOUR_TOKEN" +# or, when using shell substitution: +curl -H "Authorization: Bearer \"$YOUR_TOKEN\""shared/overlays/update-securityschemes-for-authentication.yaml (1)
12-16: Remove trailing spaces flagged by yamllint.Whitespace-only lines carry trailing spaces. Trim to satisfy yamllint.
- description: |- - The Cloud APIs use OAuth 2.0 for authentication. - - **For API Explorer (browser):** Authentication is handled automatically. Click "Get token" on any endpoint to authenticate with your Redpanda Cloud account and include a bearer token for requests made in API Explorer. - - **For programmatic access (CLI, SDKs, scripts):** You must create a service account in the Redpanda Cloud UI and use the OAuth 2.0 client credentials flow to obtain an access token. See the Authentication topic for detailed instructions. - + description: |- + The Cloud APIs use OAuth 2.0 for authentication. + + **For API Explorer (browser):** Authentication is handled automatically. Click "Get token" on any endpoint to authenticate with your Redpanda Cloud account and include a bearer token for requests made in API Explorer. + + **For programmatic access (CLI, SDKs, scripts):** You must create a service account in the Redpanda Cloud UI and use the OAuth 2.0 client credentials flow to obtain an access token. See the Authentication topic for detailed instructions. +cloud-dataplane/x-topics/quickstart.md (2)
21-26: Remove duplicated warning block.The page repeats the same warning twice. Keep a single warning near the top of the section.
-> **Warning:** API requests from the API Explorer are executed against your actual environment and data, not a sandbox. - ## Create a topic -> **Warning:** API requests from this page are executed against your actual environment and data, not a sandbox. +> **Warning:** API requests from the API Explorer are executed against your actual environment and data, not a sandbox.
29-32: Ensure UI labeling matches the new server variable (subdomain vs full URL).The instruction says “Data Plane API URL field” but the overlay switches to a subdomain variable. Align the wording to prevent user error.
- From the `dataplane_api.url` value in the response, extract only the subdomain (the part between `https://` and `.cloud.redpanda.com`). Enter this value in the Data Plane API URL field. + From the `dataplane_api.url` value in the response, extract only the subdomain (the part between `https://` and `.cloud.redpanda.com`). Enter this value in the Data Plane API subdomain field.If the UI still shows “URL,” consider “Data Plane API URL (subdomain)” to disambiguate.
cloud-controlplane/x-topics/quickstart.md (5)
1-1: Use consistent terminology: “Control Plane API”.
Align with the rest of the docset that uses “Control Plane API”.Apply this diff:
-The following steps describe how to authenticate with the Control API and create a new Redpanda cluster. For more information on the Control Plane API, see the [Cloud API Overview](#topic-cloud-api-overview). +The following steps describe how to authenticate with the Control Plane API and create a new Redpanda cluster. For more information on the Control Plane API, see the [Cloud API Overview](#topic-cloud-api-overview).
31-31: Minor wording: “In the dropdown” reads better than “On the dropdown”.
Improves readability/consistency with other UI instructions.Apply this diff:
-1. On the **Choose an operation** dropdown, select **Create resource group**. +1. In the **Choose an operation** dropdown, select **Create resource group**.
41-41: Minor wording: “In the dropdown” reads better than “On the dropdown”.
Same phrasing improvement as above for consistency.Apply this diff:
-1. On the dropdown, select **Create network**. +1. In the dropdown, select **Create network**.
67-67: Minor wording: “In the dropdown” reads better than “On the dropdown”.
Keep UI phrasing consistent across flows.Apply this diff:
-1. In the subheader, open **API Explorer**. +1. In the subheader, open **API Explorer**.Note: If you intended to update a different “On the dropdown” line in this section (e.g., selecting an operation), mirror the earlier change to use “In the dropdown”.
69-69: Minor wording: “In the dropdown” reads better than “On the dropdown”.
Consistency with earlier steps.Apply this diff:
-1. On the **Choose an operation** dropdown, select **Create resource group**. +1. In the **Choose an operation** dropdown, select **Create resource group**.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
cloud-controlplane/x-topics/quickstart.md(3 hunks)cloud-dataplane/cloud-dataplane.yaml(1 hunks)cloud-dataplane/overlays/update-dataplane-server-config.yaml(1 hunks)cloud-dataplane/x-topics/quickstart.md(2 hunks)shared/overlays/update-securityschemes-for-authentication.yaml(1 hunks)shared/x-topics/about-authentication.md(2 hunks)shared/x-topics/cloud-api-deprecation-policy.md(0 hunks)shared/x-topics/cloud-api-overview.md(3 hunks)
💤 Files with no reviewable changes (1)
- shared/x-topics/cloud-api-deprecation-policy.md
🧰 Additional context used
🪛 YAMLlint (1.37.1)
shared/overlays/update-securityschemes-for-authentication.yaml
[error] 12-12: trailing spaces
(trailing-spaces)
[error] 14-14: trailing spaces
(trailing-spaces)
[error] 16-16: trailing spaces
(trailing-spaces)
cloud-dataplane/overlays/update-dataplane-server-config.yaml
[error] 19-19: trailing spaces
(trailing-spaces)
🪛 markdownlint-cli2 (0.17.2)
shared/x-topics/cloud-api-overview.md
49-49: Link fragments should be valid
(MD051, link-fragments)
70-70: Link fragments should be valid
(MD051, link-fragments)
cloud-dataplane/x-topics/quickstart.md
1-1: Link fragments should be valid
(MD051, link-fragments)
cloud-controlplane/x-topics/quickstart.md
1-1: Link fragments should be valid
(MD051, link-fragments)
🪛 LanguageTool
cloud-controlplane/x-topics/quickstart.md
[grammar] ~3-~3: There might be a mistake here.
Context: ...trol plane and data plane architecture. To view the available endpoints for mana...
(QB_NEW_EN)
[grammar] ~92-~92: There might be a mistake here.
Context: ...mple Create topic or List users. 1. In the URL field, add the data plane API...
(QB_NEW_EN)
🔇 Additional comments (3)
shared/x-topics/cloud-api-overview.md (1)
49-49: Update deprecation policy link to match the site’s canonical anchorThe current anchor
#topic-deprecation-policydoesn’t exist inshared/x-topics/cloud-api-deprecation-policy.md. Please adjust both occurrences to the correct URL/anchor used by the built docs. For example, if you’re targeting the “Deprecation notice and timelines” section, update to:/shared/x-topics/cloud-api-deprecation-policy.md#deprecation-notice-and-timelines
Affected locations:
- shared/x-topics/cloud-api-overview.md: line 49
- shared/x-topics/cloud-api-overview.md: line 70
Verify against your site build’s routing or front-matter slug to ensure the link resolves.
cloud-dataplane/overlays/update-dataplane-server-config.yaml (1)
10-11: Server URL template change looks correct and aligns with API Explorer UX.
The variable name aligns with the description below. This should make the input experience clearer for users.cloud-controlplane/x-topics/quickstart.md (1)
17-22: Auth guidance for API Explorer is clear and actionable.
Token acquisition, validity, and scope are described succinctly.
| @@ -1,7 +1,7 @@ | |||
| The following steps describe how to authenticate with the Control API and create a new Redpanda cluster. For more information on the Control Plane API, see the Cloud API Overview. | |||
| The following steps describe how to authenticate with the Control API and create a new Redpanda cluster. For more information on the Control Plane API, see the [Cloud API Overview](#topic-cloud-api-overview). | |||
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Validate anchor link to “Cloud API Overview”.
The fragment link [#topic-cloud-api-overview] may not resolve if the target anchor isn’t present on the rendered page. Please verify the site build includes that anchor.
Run this script to check if the anchor exists anywhere in the repo and whether this file has a local anchor alternative. If it doesn’t exist, consider linking to the Cloud API Overview page path instead of a fragment.
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Searching for occurrences of 'topic-cloud-api-overview'..."
rg -n "topic-cloud-api-overview" -A 2 -B 2 || true
echo
echo "Checking for a local heading that could be used as an anchor in this file..."
rg -n "^#{1,6}\\s+Cloud API Overview" -A 2 -B 2 cloud-controlplane/x-topics/quickstart.md || trueLength of output: 1447
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Searching all MD files for a 'Cloud API Overview' heading..."
rg -n "^#{1,6}\\s+Cloud API Overview" -A 2 -B 2 --glob "*.md" || trueLength of output: 226
Broken anchor link to Cloud API Overview
No ## Cloud API Overview heading was found in the repo, so the fragment #topic-cloud-api-overview will 404. Please update the link by doing one of the following:
- Add a
## Cloud API Overviewheading on the target page so#topic-cloud-api-overviewresolves. - Or replace the fragment link with the actual path to the Cloud API Overview page (for example,
/cloud-controlplane/cloud-api-overview/).
Affected file:
- cloud-controlplane/x-topics/quickstart.md (line 1)
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
1-1: Link fragments should be valid
(MD051, link-fragments)
🤖 Prompt for AI Agents
In cloud-controlplane/x-topics/quickstart.md around lines 1 to 1, the inline
fragment link `#topic-cloud-api-overview` is broken because no `## Cloud API
Overview` heading exists; either add a matching `## Cloud API Overview` heading
to the target page so the fragment resolves, or replace the fragment with the
correct path to the Cloud API Overview page (for example
`/cloud-controlplane/cloud-api-overview/`) and update the markdown link
accordingly so it no longer 404s.
There was a problem hiding this comment.
That is the correct syntax for creating a relative link to an x-topic added to the page.
There was a problem hiding this comment.
@kbatuigas Thank you for the clarification! I understand now that #topic-cloud-api-overview is the correct syntax for linking to x-topics in your documentation system. I apologize for flagging this as a broken link - I was applying standard markdown fragment link rules without understanding how your x-topic processing works.
✏️ Learnings added
Learnt from: kbatuigas
PR: redpanda-data/api-docs#15
File: cloud-controlplane/x-topics/quickstart.md:1-1
Timestamp: 2025-08-14T00:11:35.443Z
Learning: In the Redpanda API docs system, fragment links with the syntax `#topic-[topic-name]` are the correct way to create relative links to x-topics that get added to pages during the build process. These fragments resolve correctly even if the corresponding heading isn't visible in the raw markdown files.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
| 1. Retrieve your cluster's data plane API URL by making a **Get cluster** (BYOC, Dedicated) or **Get Serverless cluster** (Serverless) request in the API Explorer. | ||
|
|
||
| 1. Save the value of `dataplane_api.url` from the response body. | ||
| 1. From the **Redpanda APIs** selector, go to **Cloud Data Plane API**. | ||
| 1. Select an operation, for example **Create topic** or **List users**. | ||
| 1. In the URL field, add the data plane API URL. You can now make Data Plane API requests to your target cluster. | ||
|
|
There was a problem hiding this comment.
Align “Next steps” with the new API Explorer input (subdomain vs full URL).
The Data Plane overlay now expects only the subdomain to be entered in the URL field. The current text asks users to add the full data plane API URL, which conflicts with the updated UI/overlay.
Apply this diff to clarify extracting and entering the subdomain (and fix wording “add” → “enter”):
-1. Retrieve your cluster's data plane API URL by making a **Get cluster** (BYOC, Dedicated) or **Get Serverless cluster** (Serverless) request in the API Explorer.
-1. Save the value of `dataplane_api.url` from the response body.
-1. From the **Redpanda APIs** selector, go to **Cloud Data Plane API**.
-1. Select an operation, for example **Create topic** or **List users**.
-1. In the URL field, add the data plane API URL. You can now make Data Plane API requests to your target cluster.
+1. Retrieve your cluster's data plane API URL by making a **Get cluster** (BYOC, Dedicated) or **Get Serverless cluster** (Serverless) request in the API Explorer.
+1. Save the value of `dataplane_api.url` from the response body. From this URL, extract the subdomain (the part between `https://` and `.cloud.redpanda.com`). For example, if the URL is `https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com`, the subdomain is `api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd`.
+1. From the **Redpanda APIs** selector, go to **Cloud Data Plane API**.
+1. Select an operation, for example **Create topic** or **List users**.
+1. In the URL field, enter the subdomain you extracted. You can now make Data Plane API requests to your target cluster.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 1. Retrieve your cluster's data plane API URL by making a **Get cluster** (BYOC, Dedicated) or **Get Serverless cluster** (Serverless) request in the API Explorer. | |
| 1. Save the value of `dataplane_api.url` from the response body. | |
| 1. From the **Redpanda APIs** selector, go to **Cloud Data Plane API**. | |
| 1. Select an operation, for example **Create topic** or **List users**. | |
| 1. In the URL field, add the data plane API URL. You can now make Data Plane API requests to your target cluster. | |
| 1. Retrieve your cluster's data plane API URL by making a **Get cluster** (BYOC, Dedicated) or **Get Serverless cluster** (Serverless) request in the API Explorer. | |
| 1. Save the value of `dataplane_api.url` from the response body. From this URL, extract the subdomain (the part between `https://` and `.cloud.redpanda.com`). For example, if the URL is `https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com`, the subdomain is `api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd`. | |
| 1. From the **Redpanda APIs** selector, go to **Cloud Data Plane API**. | |
| 1. Select an operation, for example **Create topic** or **List users**. | |
| 1. In the URL field, enter the subdomain you extracted. You can now make Data Plane API requests to your target cluster. |
🧰 Tools
🪛 LanguageTool
[grammar] ~92-~92: There might be a mistake here.
Context: ...mple Create topic or List users. 1. In the URL field, add the data plane API...
(QB_NEW_EN)
🤖 Prompt for AI Agents
In cloud-controlplane/x-topics/quickstart.md around lines 88 to 94, the
instructions currently tell users to add the full data plane API URL to the API
Explorer but the overlay now expects only the subdomain; update the text to
instruct users to save dataplane_api.url from the response, extract the
subdomain (strip the scheme and any path, leaving only the host like
"abc-123.region.redpanda.cloud"), then in the API Explorer select Cloud Data
Plane API, choose an operation (e.g., Create topic or List users), and enter
that subdomain into the URL field (replace the word "add" with "enter" and
include a short note describing how to extract the subdomain).
| url: '{dataplane_api_url}' | ||
| variables: | ||
| dataplane_api_url: | ||
| default: "dataplane_api.url" | ||
| default: https://{dataplane_api_url} | ||
| description: |- | ||
| Find the Data Plane API base URL of a cluster by calling the Get Cluster endpoint of the Control Plane API. The dataplane_api.url field is returned in the response body.<br><br> | ||
| Example (Dedicated): "https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com"<br> | ||
| Find the Data Plane API base URL of a cluster by calling the Get Cluster endpoint of the Control Plane API. The dataplane_api.url field is returned in the response body. | ||
|
|
||
| Example (BYOC): "https://api-a4cb21.ck09mi9c4vs17hng9gig.byoc.prd.cloud.redpanda.com" | ||
| Example (Dedicated): "https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com" |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Confirm overlay compatibility with the base spec.
The PR adds an overlay to change server URL templating. Ensure the overlay’s target paths and variable names match this base file to avoid broken API Explorer input fields.
🏁 Script executed:
#!/bin/bash
# Inspect the overlay to confirm it updates servers[0].url and variables consistently.
fd -a update-dataplane-server-config.yaml
if [ $? -eq 0 ]; then
cat $(fd -a update-dataplane-server-config.yaml)
else
echo "Overlay file not found. Verify repository path and filename."
fiLength of output: 1223
🏁 Script executed:
#!/bin/bash
# Show context around the servers definition to confirm JSON Path applicability
sed -n '4960,5010p' cloud-dataplane/cloud-dataplane.yamlLength of output: 2357
Overlay JSONPaths Verified, But Variable Placeholder Mismatch
- The overlay correctly targets
$.servers[0].urland$.servers[0].variables. - You’ve renamed the server variable from
dataplane_api_urltodataplane_api_subdomain, but the default value in your overlay is set to{dataplane.api.subdomain}(dots) rather than{dataplane_api_subdomain}(underscores). This discrepancy will misalign the UI’s input field and may confuse or break the API Explorer. - Please update the default placeholder to
{dataplane_api_subdomain}so it matches the variable name exactly. - Also double-check that replacing the entire
variablesblock won’t inadvertently remove any other server variables if they’re ever added upstream.
🤖 Prompt for AI Agents
In cloud-dataplane/cloud-dataplane.yaml around lines 4979 to 4987, the server
variable name was changed to dataplane_api_subdomain but the default placeholder
still uses dots ({dataplane.api.subdomain}); update the default to use the exact
variable placeholder {dataplane_api_subdomain} so the UI input maps correctly,
and instead of wholesale replacing the variables block, merge changes to
preserve any existing or future server variables (i.e., keep other keys intact
when updating the default placeholder).
Self-referential server variable default breaks URL templating.
variables.dataplane_api_url.default points to https://{dataplane_api_url}, which recursively references itself and yields an invalid default. Provide a concrete default (full URL), or switch to a subdomain variable and construct the URL in the server url.
Option A (keep full URL variable):
servers:
- description: Data Plane API
- url: '{dataplane_api_url}'
+ url: '{dataplane_api_url}'
variables:
dataplane_api_url:
- default: https://{dataplane_api_url}
- description: |-
- Find the Data Plane API base URL of a cluster by calling the Get Cluster endpoint of the Control Plane API. The dataplane_api.url field is returned in the response body.
+ default: https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com
+ description: |-
+ Use the full Data Plane API base URL for the target cluster. Retrieve it by calling the Control Plane API “Get Cluster” endpoint and copy the dataplane_api.url value from the response.
- Example (BYOC): "https://api-a4cb21.ck09mi9c4vs17hng9gig.byoc.prd.cloud.redpanda.com"
- Example (Dedicated): "https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com"
+ Example (BYOC): https://api-a4cb21.ck09mi9c4vs17hng9gig.byoc.prd.cloud.redpanda.com
+ Example (Dedicated): https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.comOption B (align with overlay using subdomain variable):
- - description: Data Plane API
- url: '{dataplane_api_url}'
- variables:
- dataplane_api_url:
- default: https://{dataplane_api_url}
- description: |-
- Find the Data Plane API base URL of a cluster by calling the Get Cluster endpoint of the Control Plane API. The dataplane_api.url field is returned in the response body.
- Example (BYOC): "https://api-a4cb21.ck09mi9c4vs17hng9gig.byoc.prd.cloud.redpanda.com"
- Example (Dedicated): "https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com"
+ - description: Data Plane API
+ url: 'https://{dataplane_api_subdomain}.cloud.redpanda.com'
+ variables:
+ dataplane_api_subdomain:
+ default: api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd
+ description: |-
+ Extract the subdomain from the Data Plane API URL returned by the Control Plane API (dataplane_api.url) and enter it here.
+ Example (BYOC): api-a4cb21.ck09mi9c4vs17hng9gig.byoc.prd
+ Example (Dedicated): api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prdPick one approach and ensure the overlay doesn’t conflict.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| url: '{dataplane_api_url}' | |
| variables: | |
| dataplane_api_url: | |
| default: "dataplane_api.url" | |
| default: https://{dataplane_api_url} | |
| description: |- | |
| Find the Data Plane API base URL of a cluster by calling the Get Cluster endpoint of the Control Plane API. The dataplane_api.url field is returned in the response body.<br><br> | |
| Example (Dedicated): "https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com"<br> | |
| Find the Data Plane API base URL of a cluster by calling the Get Cluster endpoint of the Control Plane API. The dataplane_api.url field is returned in the response body. | |
| Example (BYOC): "https://api-a4cb21.ck09mi9c4vs17hng9gig.byoc.prd.cloud.redpanda.com" | |
| Example (Dedicated): "https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com" | |
| - description: Data Plane API | |
| url: 'https://{dataplane_api_subdomain}.cloud.redpanda.com' | |
| variables: | |
| dataplane_api_subdomain: | |
| default: api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd | |
| description: |- | |
| Extract the subdomain from the Data Plane API URL returned by the Control Plane API (dataplane_api.url) and enter it here. | |
| Example (BYOC): api-a4cb21.ck09mi9c4vs17hng9gig.byoc.prd | |
| Example (Dedicated): api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd |
There was a problem hiding this comment.
The overlay is meant to update servers.url so that API doc readers can correctly use the Bump API Explorer, which requires that the domain is defined. https://docs.bump.sh/help/documentation-experience/api-explorer/#server-variables
There was a problem hiding this comment.
@kbatuigas Thank you for the clarification! That makes perfect sense. The Bump API Explorer does indeed require the domain to be defined in the server URL template rather than as a variable placeholder for proper functionality.
Your overlay approach is the correct solution - constructing the full URL as https://{dataplane_api_subdomain}.cloud.redpanda.com in the server URL field while having users input just the subdomain portion. This resolves both the circular reference issue in the base file and meets Bump API Explorer's requirements.
However, there's still one small inconsistency in the overlay: the variable name is dataplane_api_subdomain (with underscores) but the default placeholder uses {dataplane.api.subdomain} (with dots). For consistency, the default should be {dataplane_api_subdomain} to match the variable name exactly.
The overlay implementation is the right approach for your Bump API Explorer compatibility needs!
(\ /)
( ._.)
o_(")(") *curious about API Explorer requirements*
✏️ Learnings added
Learnt from: kbatuigas
PR: redpanda-data/api-docs#15
File: cloud-dataplane/cloud-dataplane.yaml:4979-4987
Timestamp: 2025-08-14T00:22:44.828Z
Learning: Bump API Explorer requires server variables to have the domain defined in the server URL template rather than as a variable placeholder. When using overlays for API documentation tools like Bump, construct the full URL in the server.url field (e.g., `https://{variable_name}.domain.com`) rather than using the variable as the entire URL.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
| - target: "$.servers[0].variables" | ||
| update: | ||
| dataplane_api_subdomain: | ||
| default: "{dataplane.api.subdomain}" |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Avoid clobbering the entire servers[0].variables object.
Targeting the whole variables object risks overwriting other server variables that may exist upstream. Update just the specific variable instead.
Apply this diff to scope the update to only the intended variable:
- # Update only the variables section
- - target: "$.servers[0].variables"
- update:
- dataplane_api_subdomain:
- default: "{dataplane.api.subdomain}"
- description: |-
- From the `dataplane_api.url` value in the Control Plane API response, extract the subdomain (the part between `https://` and `.cloud.redpanda.com`). Enter this value in the Data Plane API URL field.
-
- Example: If the URL is `https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com`, enter `api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd`.
+ # Update only the intended variable without replacing the whole variables object
+ - target: "$.servers[0].variables.dataplane_api_subdomain"
+ update:
+ default: "{dataplane.api.subdomain}"
+ description: |-
+ From the `dataplane_api.url` value in the Control Plane API response, extract the subdomain (the part between `https://` and `.cloud.redpanda.com`). Enter this value in the Data Plane API URL field.
+
+ Example: If the URL is `https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com`, enter `api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd`.Additionally, please verify that servers[0] consistently refers to the Data Plane server in the upstream spec to avoid accidental edits if server ordering changes.
🏁 Script executed:
#!/bin/bash
# Display the first 50 lines of the overlay to verify structure and context
sed -n '1,50p' cloud-dataplane/overlays/update-dataplane-server-config.yaml
# Search for any other references to servers[0] in this overlay
grep -R "servers\\[0\\]" -n cloud-dataplane/overlays/update-dataplane-server-config.yaml || trueLength of output: 1189
🏁 Script executed:
#!/bin/bash
# Search for top-level 'servers:' definitions in base spec YAMLs (excluding overlays)
grep -R -n '^servers:' cloud-dataplane --include='*.yaml' --exclude-dir='overlays' || true
# If any found, print the first 20 lines of each file containing 'servers:'
grep -R -l '^servers:' cloud-dataplane --include='*.yaml' --exclude-dir='overlays' | while read file; do
echo "------ $file ------"
sed -n '1,20p' "$file"
doneLength of output: 969
🏁 Script executed:
#!/bin/bash
# Print the server definitions around line 4977 to confirm ordering and identify the Data Plane server
sed -n '4965,5050p' cloud-dataplane/cloud-dataplane.yamlLength of output: 2215
Scope the variable update to just dataplane_api_subdomain
Confirmed that in the base spec (cloud-dataplane/cloud-dataplane.yaml lines 4965–5050) the first (and only) entry in servers is the Data Plane API, so servers[0] is safe today—but overwriting $.servers[0].variables would remove the existing dataplane_api_url. Instead, apply:
- - target: "$.servers[0].variables"
- update:
- dataplane_api_subdomain:
- default: "{dataplane.api.subdomain}"
- description: |-
- From the `dataplane_api.url` value in the Control Plane API response, extract the subdomain (the part between `https://` and `.cloud.redpanda.com`). Enter this value in the Data Plane API URL field.
-
- Example: If the URL is `https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com`, enter `api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd`.
+ - target: "$.servers[0].variables.dataplane_api_subdomain"
+ update:
+ default: "{dataplane.api.subdomain}"
+ description: |-
+ From the `dataplane_api.url` value in the Control Plane API response, extract the subdomain (the part between `https://` and `.cloud.redpanda.com`). Enter this value in the Data Plane API URL field.
+
+ Example: If the URL is `https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com`, enter `api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd`.Also keep in mind that if additional servers are added upstream, relying on index 0 may break. Verify ordering or switch to identifying the Data Plane server by name/description if possible.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - target: "$.servers[0].variables" | |
| update: | |
| dataplane_api_subdomain: | |
| default: "{dataplane.api.subdomain}" | |
| - target: "$.servers[0].variables.dataplane_api_subdomain" | |
| update: | |
| default: "{dataplane.api.subdomain}" | |
| description: |- | |
| From the `dataplane_api.url` value in the Control Plane API response, extract the subdomain (the part between `https://` and `.cloud.redpanda.com`). Enter this value in the Data Plane API URL field. | |
| Example: If the URL is `https://api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd.cloud.redpanda.com`, enter `api-a4cb21.ck09mi9c4vs17hng9gig.fmc.prd`. |
🤖 Prompt for AI Agents
In cloud-dataplane/overlays/update-dataplane-server-config.yaml lines 13–16, the
overlay currently replaces the entire $.servers[0].variables object which
removes existing vars like dataplane_api_url; change the target to only set the
dataplane_api_subdomain key (e.g. use
"$.servers[0].variables.dataplane_api_subdomain" as the JSONPath) and update its
default value accordingly so you don't clobber other variables. Additionally, to
avoid relying on index 0 which may change upstream, prefer selecting the Data
Plane server by a stable property (e.g. description or name) in the JSONPath
(for example use a filter like "$.servers[?(@.description=='Data Plane
API')].variables.dataplane_api_subdomain") if your overlay tooling supports it.
| default: "{dataplane.api.subdomain}" | ||
| description: |- | ||
| From the `dataplane_api.url` value in the Control Plane API response, extract the subdomain (the part between `https://` and `.cloud.redpanda.com`). Enter this value in the Data Plane API URL field. | ||
|
|
There was a problem hiding this comment.
Fix YAML trailing whitespace (linter error).
There are trailing spaces on this blank line that break YAMLlint.
Apply this diff to remove trailing whitespace:
-
+📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
🧰 Tools
🪛 YAMLlint (1.37.1)
[error] 19-19: trailing spaces
(trailing-spaces)
🤖 Prompt for AI Agents
In cloud-dataplane/overlays/update-dataplane-server-config.yaml around line 19,
there is a blank line containing trailing whitespace that causes YAML linting to
fail; remove the trailing spaces on that blank line so it is truly empty (no
spaces or tabs), then re-run the linter to confirm the warning is resolved.
In trying to ensure that we clearly describe how authentication works in the API Explorer, I realized that there might be too many significant changes that need to be approved and backported in the source data plane spec file. Some of the pertinent fields in the spec files that would be affected are used by tooling in console/cloudv2. To avoid breaking anything upstream, we can use overlays instead to modify the spec files to reflect the API Explorer experience.
This pull request updates documentation and API configuration to clarify authentication methods (browser vs. programmatic), improve instructions for using the API Explorer, and align API server URL handling with expected usage. The changes help users distinguish between authentication flows, correctly extract and use the Data Plane API URL, and improve compatibility with API Explorer tools.
Authentication Documentation Improvements:
about-authentication.mdto clearly separate browser-based (API Explorer) and programmatic authentication, describing OAuth 2.0 Implicit Flow for browser use and Client Credentials Flow for scripts/SDKs. [1] [2]auth0security scheme description to distinguish between API Explorer and programmatic authentication, with clearer instructions for each.API Explorer and Quickstart Guide Updates:
quickstart.md) for Control Plane and Data Plane APIs to clarify API Explorer usage, step-by-step resource creation, and the process of extracting and using the correct subdomain from the Data Plane API URL. [1] [2] [3]API Server URL Configuration:
cloud-dataplane.yamlserver URL and variables to better match how users should enter the Data Plane API subdomain, and provided a clear example in the description.update-dataplane-server-config.yaml) to update the server URL template and variable description for improved API Explorer compatibility and user guidance on extracting the subdomain.