DC-5694 OAuth Clarification #7205

aidankmcalister · 2025-10-22T15:37:32Z

Summary by CodeRabbit

Documentation
- Reworked Authentication to present Service tokens and OAuth 2.0 access tokens, replacing prior Bearer-token emphasis.
- Added Service tokens subsection with streamlined creation steps and header usage examples.
- Added full OAuth 2.0 auth-code flow with example requests, updated token naming/JSON examples, Postman/Swagger OAuth details, redirect guidance, and updated Management API playground instructions (removed iframe).
- Minor formatting and anchor updates.
Chores
- Increased link-checker retry limit and adjusted cache duration note in CI.

github-actions · 2025-10-22T15:37:52Z

Dangerous URL check

No absolute URLs to prisma.io/docs found.
No local URLs found.

github-actions · 2025-10-22T15:37:58Z

original	preview
content/250-postgres/100-introduction/230-management-api.mdx	content/250-postgres/100-introduction/230-management-api.mdx
content/800-guides/330-management-api-basic.mdx	content/800-guides/330-management-api-basic.mdx

github-actions · 2025-10-22T15:38:02Z

Redirect check

This PR probably requires the following redirects to be added to static/_redirects:

This PR does not change any pages in a way that would require a redirect.

coderabbitai · 2025-10-22T15:38:05Z

Walkthrough

Replaces the Management API's single Bearer-token auth with two methods: Service tokens (UI creation, header usage) and OAuth 2.0 (authorization code flow, token exchange). Updates curl/Postman/Swagger examples, replaces the iframe playground with a commented/alternating playground block, updates an internal anchor, and adjusts lychee workflow cache/retry/exclude settings.

Changes

Cohort / File(s)	Change summary
Management API auth doc `content/250-postgres/100-introduction/230-management-api.mdx`	Rewrote Authentication section: removed Bearer-token-centric flow; added Service tokens subsection (Settings → Service Tokens → New Service Token) and header usage; added OAuth 2.0 subsection with credential creation, authorization URL/redirect handling, and authorization-code→token curl example; updated Authorization header naming and JSON formatting in examples; reworked Postman/Swagger OAuth instructions and redirect URI guidance; replaced iframe-based Management API playground with a commented/alternating playground block; removed obsolete playground endpoint block; miscellaneous formatting/indentation adjustments.
Guide anchor update `content/800-guides/330-management-api-basic.mdx`	Updated internal anchor link to point to the new Service Tokens section (`#service-tokens`) instead of the old Bearer-token anchor.
CI: lychee workflow `.github/workflows/lychee.yml`	Updated lychee invocation: changed `--max-cache-age` from 3h to 5m, increased `--max-retries` from 5 to 8, removed several broad exclude patterns and replaced with a narrower `--exclude 'https://cockroachlabs.com'`, and updated Lychee report/cache-duration notes accordingly.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

feat: updated docs for 6.15 #7083 — Overlapping edits to the Management API authentication content (replacing bearer/integration-token flows with service-token and OAuth flows).
fix: add new service token steps #7072 — Updates service-token creation UI path/instructions to "Settings → Service Tokens → New Service Token", matching changes here.
DC-5259 Added Lychee Link Checker #7192 — Modifies the same .github/workflows/lychee.yml workflow flags (cache age, excludes, retries), related CI change.

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title “DC-5694 OAuth Clarification” clearly refers to the OAuth-focused updates in the management API documentation, which represent a significant portion of the changes. However, the updates also include the introduction of service tokens and improvements to the management API playground, which are not reflected in the title. Including the Jira ticket ID adds noise and does not aid in understanding the content. Nevertheless, the title is concise and refers to a real aspect of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e0f9b38 and 93f1251.

📒 Files selected for processing (1)

.github/workflows/lychee.yml (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

.github/workflows/lychee.yml

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2025-10-22T15:38:47Z

🍈 Lychee Link Check Report

Note: Links are cached for 3 hours to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2324
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	91
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	1
Full Github Actions output

cloudflare-workers-and-pages · 2025-10-22T15:39:40Z

Deploying docs with Cloudflare Pages

Latest commit:	`93f1251`
Status:	✅ Deploy successful!
Preview URL:	https://cff863d4.docs-51g.pages.dev
Branch Preview URL:	https://dc-5694-oauth-clarification.docs-51g.pages.dev

View logs

github-actions · 2025-10-22T15:42:25Z

🍈 Lychee Link Check Report

Note: Links are cached for 3 hours to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2324
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	91
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	1
Full Github Actions output

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

content/800-guides/330-management-api-basic.mdx (1)

1-200: Consider adding an OAuth 2.0 alternative or cross-reference.

Since the PR updates authentication docs to clarify OAuth 2.0 as an explicit authentication method alongside service tokens, this "basic" guide currently only demonstrates service token authentication. Consider whether this guide should:

Mention OAuth 2.0 as an alternative authentication method

Cross-reference users to the main management API docs for OAuth 2.0 guidance

Remain service-token-focused as a beginner-friendly starting point

This depends on the intended audience scope for this guide. If this is meant as the simplest entry point, service-tokens-only is reasonable with a note that OAuth 2.0 is available in advanced scenarios.

Please clarify the intended scope: should this guide remain service-token-focused for beginners, or should it acknowledge OAuth 2.0 as an available alternative?

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e30bfde and af557fd.

📒 Files selected for processing (1)

content/800-guides/330-management-api-basic.mdx (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

GitHub Check: Check internal links
GitHub Check: runner / linkspector
GitHub Check: Cloudflare Pages

🔇 Additional comments (1)

content/800-guides/330-management-api-basic.mdx (1)

15-15: No action required—the anchor reference is valid.

The heading ### Service tokens exists on line 44 of the referenced management API documentation file. MDX automatically generates the anchor #service-tokens from this heading, so the link reference on line 15 is correct and functional.

github-actions · 2025-10-22T15:51:05Z

🍈 Lychee Link Check Report

Note: Links are cached for 3 hours to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2322
⏳ Timeouts	2
🔀 Redirected	0
👻 Excluded	91
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	1

Errors per input

Errors in 800-guides/160-tanstack-start.mdx

[TIMEOUT] https://tanstack.com/start/latest/docs/framework/react/build-from-scratch | Timeout
[TIMEOUT] https://tanstack.com/start/latest/docs/framework/react/overview | Timeout
Full Github Actions output

github-actions · 2025-10-22T15:56:51Z

🍈 Lychee Link Check Report

Note: Links are cached for 3 hours to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2324
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	91
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	1
Full Github Actions output

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

.github/workflows/lychee.yml (1)

31-31: Reasonable adjustment to support expanded documentation validation.

The increased retry count aligns well with the PR's expanded OAuth documentation and restructured content, which likely introduces additional links that benefit from more robust validation. The change is straightforward and introduces negligible timing overhead.

Optional improvement: Consider adding a brief inline comment (e.g., # Increased for expanded OAuth docs validation) to document the rationale for future maintainers, especially if this is a non-standard number for your project.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 226391f and e659d12.

📒 Files selected for processing (1)

.github/workflows/lychee.yml (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

GitHub Check: runner / linkspector
GitHub Check: Check internal links

github-actions · 2025-10-22T18:27:24Z

🍈 Lychee Link Check Report

Note: Links are cached for 3 hours to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2324
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	91
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	1
Full Github Actions output

github-actions · 2025-10-22T19:20:41Z

🍈 Lychee Link Check Report

Note: Links are cached for 3 hours to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2324
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	91
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	1
Full Github Actions output

github-actions · 2025-10-22T19:23:51Z

🍈 Lychee Link Check Report

Note: Links are cached for 10 minutes to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2324
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	91
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	1
Full Github Actions output

aidankmcalister · 2025-10-22T19:25:32Z

@CodeRabbit pause

github-actions · 2025-10-22T19:26:48Z

🍈 Lychee Link Check Report

Note: Links are cached for 10 minutes to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2389
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	26
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	1
Full Github Actions output

coderabbitai · 2025-10-22T19:30:32Z

✅ Actions performed

Reviews paused.

github-actions · 2025-10-22T19:56:32Z

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2388
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	26
❓ Unknown	0
🚫 Errors	1
⛔ Unsupported	1

Errors per input

Errors in 200-orm/050-overview/500-databases/840-cockroachdb.mdx

[ERROR] https://www.cockroachlabs.com/docs/stable/data-types.html | Network error: error sending request for url (https://www.cockroachlabs.com/docs/stable/data-types.html) Maybe a certificate error?
Full Github Actions output

github-actions · 2025-10-22T20:02:33Z

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2389
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	26
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	1
Full Github Actions output

github-actions · 2025-10-22T20:10:48Z

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2387
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	26
❓ Unknown	0
🚫 Errors	2
⛔ Unsupported	1

Errors per input

Errors in 100-getting-started/02-setup-prisma/100-start-from-scratch/110-relational-databases/100-connect-your-database-node-cockroachdb.mdx

[ERROR] https://www.cockroachlabs.com/docs/stable/connection-parameters.html#additional-connection-parameters | Network error: error sending request for url (https://www.cockroachlabs.com/docs/stable/connection-parameters.html#additional-connection-parameters) Maybe a certificate error?

Errors in 100-getting-started/02-setup-prisma/200-add-to-existing-project/110-relational-databases/100-connect-your-database-typescript-cockroachdb.mdx

[ERROR] https://www.cockroachlabs.com/docs/cockroachcloud/quickstart.html | Network error: error sending request for url (https://www.cockroachlabs.com/docs/cockroachcloud/quickstart.html) Maybe a certificate error?
Full Github Actions output

github-actions · 2025-10-22T20:12:57Z

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes to avoid unnecessary requests, and speed up consecutive runs.

📊 Results Overview

Status	Count
🔍 Total	2416
✅ Successful	2389
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	26
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	1
Full Github Actions output

aidankmcalister · 2025-10-22T20:25:21Z

@CodeRabbit resume

coderabbitai · 2025-10-22T20:25:51Z

✅ Actions performed

Reviews resumed.

updated docs

e30bfde