docs(api): Add OAuth2 documentation with PKCE support

[dcramer]

• Adds comprehensive OAuth2 documentation to docs/api/auth.mdx covering authorization flow, token exchange, refresh tokens, and PKCE implementation
• Consolidates OAuth documentation by streamlining the partnership platform page to reference the central auth docs, eliminating duplication
• Includes complete Python/Flask code examples demonstrating PKCE-enabled OAuth flow

Refs getsentry/sentry#104418

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
sentry-docs	Ready	Preview, Comment	Jan 5, 2026 9:36pm

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
develop-docs	Ignored	Preview	Jan 5, 2026 9:36pm

[dcramer]

Usage by model:
        claude-haiku:  217.2k input, 3.0k output, 0 cache read, 0 cache write ($0.2320)
     claude-opus-4-5:  1.6k input, 29.0k output, 3.1m cache read, 219.8k cache write ($3.68)

[coolguyzone]

LGTM!

[sentry]

Bug: The OAuth callback example code does not check the HTTP status code before parsing the token response, causing a KeyError when the server returns an error.
_{Severity: CRITICAL | Confidence: High}

🔍 Detailed Analysis

The example code for the OAuth callback function makes a POST request to the token endpoint but does not validate the HTTP status code of the response. In common failure scenarios, such as an expired authorization code, the OAuth server will return an error response (e.g., HTTP 400) with a JSON body that does not contain access_token or refresh_token keys. The code proceeds to parse this JSON and immediately attempts to access tokens['access_token'], which raises a KeyError and causes an unhandled exception, crashing the application.

💡 Suggested Fix

Before parsing the JSON with response.json(), check if response.status_code is successful (e.g., response.raise_for_status() or if response.status_code == 200). Handle non-200 status codes gracefully instead of attempting to access token keys that will not be present in an error response.

🤖 Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: docs/api/auth.mdx#L200

Potential issue: The example code for the OAuth callback function makes a `POST` request
to the token endpoint but does not validate the HTTP status code of the response. In
common failure scenarios, such as an expired authorization code, the OAuth server will
return an error response (e.g., HTTP 400) with a JSON body that does not contain
`access_token` or `refresh_token` keys. The code proceeds to parse this JSON and
immediately attempts to access `tokens['access_token']`, which raises a `KeyError` and
causes an unhandled exception, crashing the application.

_{Did we get this right? 👍 / 👎 to inform future reviews.
Reference ID: 8192205}

[sentry]

Bug: The refresh_token function accesses session['refresh_token'] without a check, causing a KeyError if the key is not present in the session.
_{Severity: HIGH | Confidence: High}

🔍 Detailed Analysis

The refresh_token function in the example code directly accesses session['refresh_token'] without first verifying its existence. If this function is called in a scenario where the refresh token has not yet been stored in the session (e.g., due to a previous error in the callback, an expired session, or being called out of sequence), the application will raise a KeyError. This results in an unhandled exception, crashing the token refresh process.

💡 Suggested Fix

Validate the presence of the refresh_token in the session before using it. Use a safe access method like session.get('refresh_token') and handle the case where the token is None. This prevents a KeyError if the function is called on a session without a valid token.

🤖 Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: docs/api/auth.mdx#L211

Potential issue: The `refresh_token` function in the example code directly accesses
`session['refresh_token']` without first verifying its existence. If this function is
called in a scenario where the refresh token has not yet been stored in the session
(e.g., due to a previous error in the callback, an expired session, or being called out
of sequence), the application will raise a `KeyError`. This results in an unhandled
exception, crashing the token refresh process.

_{Did we get this right? 👍 / 👎 to inform future reviews.
Reference ID: 8192205}