Add PKCE documentation

[ricardobcl]

Description

Documents the Native Application Flow (PKCE) being added to the authorization server by uphold/backend#19003, for native clients (desktop, CLI, mobile) that receive the OAuth redirect on a loopback address — including the MCP client use case.

• New _authentication.md section: proof key generation (code_verifier/code_challenge, S256 only), the GET /oauth2/authorize/start endpoint with its parameters and challenge semantics (30-minute validity, bound to client_id + state, fresh state per attempt), the code_verifier token-exchange parameter with its failure mode (mismatch consumes the code), and loopback redirect URL matching (port-agnostic per RFC 8252 §7.3).
• _applications.md: loopback http redirect URLs are now registrable for native applications, with a pointer to the PKCE requirement they trigger.
• _ratelimits.md: GET /oauth2/authorize/start — 30 requests / 5-min window per IP.
• Intro updated to present the three authorization flows.

Stacked on #250 (the auth-section refresh), since both edit the same sections — this PR targets that branch and will retarget to master automatically when it merges.

Blocked — do not merge until uphold/backend#19003 is merged and deployed

Two open review items on the backend PR may require small wording updates here before merging:

• Whether /oauth2/authorize/start will reject clients that are not PKCE-required (review suggestion) — affects the "other applications may opt in" phrasing.
• Whether client authentication (client_secret) at the token endpoint will be relaxed for public clients — the Step 3 example currently shows -u <clientId>:<clientSecret>, matching today's behavior.

Related issues

• uphold/backend#19003 (blocking)
• Update authentication and rate limit documentation #250 (base branch)

Impacted areas

Authentication, Applications and Rate Limits pages of the API reference.

Steps to reproduce or test

Development

Content derived from the backend PR's implementation and description (endpoint parameters, validation rules, TTLs and rate limit verified against its diff and config).

QA

Once the backend change is deployed to sandbox, run the documented flow end to end: generate a proof key, authorize via /oauth2/authorize/start, and exchange the code with code_verifier.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• The new and updated code has good coverage.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

Merge only after uphold/backend#19003 is deployed to production, and after #250 merges (this PR is stacked on it). No files removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[ricardobcl]

uphold/backend#19003 has merged (squash fb25dd2d70), so this is now open for review. Keeping the blocked label until that change is deployed to production, since these pages go live on merge and describe the new GET /oauth2/authorize/start endpoint. One follow-up already queued: uphold/backend#19084 forwards intention on the start route — once it lands, intention should be added to the start endpoint's parameter table here.

[ricardobcl]

Description

Documents the Native Application Flow (PKCE) being added to the authorization server by uphold/backend#19003, for native clients (desktop, CLI, mobile) that receive the OAuth redirect on a loopback address — including the MCP client use case.

• New _authentication.md section: proof key generation (code_verifier/code_challenge, S256 only), the GET /oauth2/authorize/start endpoint with its parameters and challenge semantics (30-minute validity, bound to client_id + state, fresh state per attempt), the code_verifier token-exchange parameter with its failure mode (mismatch consumes the code), and loopback redirect URL matching (port-agnostic per RFC 8252 §7.3).
• _applications.md: loopback http redirect URLs are now registrable for native applications, with a pointer to the PKCE requirement they trigger.
• _ratelimits.md: GET /oauth2/authorize/start — 30 requests / 5-min window per IP.
• Intro updated to present the three authorization flows.

Stacked on #250 (the auth-section refresh), since both edit the same sections — this PR targets that branch and will retarget to master automatically when it merges.

Blocked — do not merge until uphold/backend#19003 is merged and deployed

Two open review items on the backend PR may require small wording updates here before merging:

• Whether /oauth2/authorize/start will reject clients that are not PKCE-required (review suggestion) — affects the "other applications may opt in" phrasing.
• Whether client authentication (client_secret) at the token endpoint will be relaxed for public clients — the Step 3 example currently shows -u <clientId>:<clientSecret>, matching today's behavior.

Related issues

• uphold/backend#19003 (blocking)
• Update authentication and rate limit documentation #250 (base branch)

Impacted areas

Authentication, Applications and Rate Limits pages of the API reference.

Steps to reproduce or test

Development

Content derived from the backend PR's implementation and description (endpoint parameters, validation rules, TTLs and rate limit verified against its diff and config).

QA

Once the backend change is deployed to sandbox, run the documented flow end to end: generate a proof key, authorize via /oauth2/authorize/start, and exchange the code with code_verifier.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• The new and updated code has good coverage.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

Merge only after uphold/backend#19003 is deployed to production, and after #250 merges (this PR is stacked on it). No files removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[ricardobcl]

uphold/backend#19003 has merged (squash fb25dd2d70), so this is now open for review. Keeping the blocked label until that change is deployed to production, since these pages go live on merge and describe the new GET /oauth2/authorize/start endpoint. One follow-up already queued: uphold/backend#19084 forwards intention on the start route — once it lands, intention should be added to the start endpoint's parameter table here.

[ricardobcl]

Description

Documents the Native Application Flow (PKCE) being added to the authorization server by uphold/backend#19003, for native clients (desktop, CLI, mobile) that receive the OAuth redirect on a loopback address — including the MCP client use case.

• New _authentication.md section: proof key generation (code_verifier/code_challenge, S256 only), the GET /oauth2/authorize/start endpoint with its parameters and challenge semantics (30-minute validity, bound to client_id + state, fresh state per attempt), the code_verifier token-exchange parameter with its failure mode (mismatch consumes the code), and loopback redirect URL matching (port-agnostic per RFC 8252 §7.3).
• _applications.md: loopback http redirect URLs are now registrable for native applications, with a pointer to the PKCE requirement they trigger.
• _ratelimits.md: GET /oauth2/authorize/start — 30 requests / 5-min window per IP.
• Intro updated to present the three authorization flows.

Stacked on #250 (the auth-section refresh), since both edit the same sections — this PR targets that branch and will retarget to master automatically when it merges.

Blocked — do not merge until uphold/backend#19003 is merged and deployed

Two open review items on the backend PR may require small wording updates here before merging:

• Whether /oauth2/authorize/start will reject clients that are not PKCE-required (review suggestion) — affects the "other applications may opt in" phrasing.
• Whether client authentication (client_secret) at the token endpoint will be relaxed for public clients — the Step 3 example currently shows -u <clientId>:<clientSecret>, matching today's behavior.

Related issues

• uphold/backend#19003 (blocking)
• Update authentication and rate limit documentation #250 (base branch)

Impacted areas

Authentication, Applications and Rate Limits pages of the API reference.

Steps to reproduce or test

Development

Content derived from the backend PR's implementation and description (endpoint parameters, validation rules, TTLs and rate limit verified against its diff and config).

QA

Once the backend change is deployed to sandbox, run the documented flow end to end: generate a proof key, authorize via /oauth2/authorize/start, and exchange the code with code_verifier.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• The new and updated code has good coverage.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

Merge only after uphold/backend#19003 is deployed to production, and after #250 merges (this PR is stacked on it). No files removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[ricardobcl]

uphold/backend#19003 has merged (squash fb25dd2d70), so this is now open for review. Keeping the blocked label until that change is deployed to production, since these pages go live on merge and describe the new GET /oauth2/authorize/start endpoint. One follow-up already queued: uphold/backend#19084 forwards intention on the start route — once it lands, intention should be added to the start endpoint's parameter table here.

[ricardobcl]

Description

Documents the Native Application Flow (PKCE) being added to the authorization server by uphold/backend#19003, for native clients (desktop, CLI, mobile) that receive the OAuth redirect on a loopback address — including the MCP client use case.

• New _authentication.md section: proof key generation (code_verifier/code_challenge, S256 only), the GET /oauth2/authorize/start endpoint with its parameters and challenge semantics (30-minute validity, bound to client_id + state, fresh state per attempt), the code_verifier token-exchange parameter with its failure mode (mismatch consumes the code), and loopback redirect URL matching (port-agnostic per RFC 8252 §7.3).
• _applications.md: loopback http redirect URLs are now registrable for native applications, with a pointer to the PKCE requirement they trigger.
• _ratelimits.md: GET /oauth2/authorize/start — 30 requests / 5-min window per IP.
• Intro updated to present the three authorization flows.

Stacked on #250 (the auth-section refresh), since both edit the same sections — this PR targets that branch and will retarget to master automatically when it merges.

Blocked — do not merge until uphold/backend#19003 is merged and deployed

Two open review items on the backend PR may require small wording updates here before merging:

• Whether /oauth2/authorize/start will reject clients that are not PKCE-required (review suggestion) — affects the "other applications may opt in" phrasing.
• Whether client authentication (client_secret) at the token endpoint will be relaxed for public clients — the Step 3 example currently shows -u <clientId>:<clientSecret>, matching today's behavior.

Related issues

• uphold/backend#19003 (blocking)
• Update authentication and rate limit documentation #250 (base branch)

Impacted areas

Authentication, Applications and Rate Limits pages of the API reference.

Steps to reproduce or test

Development

Content derived from the backend PR's implementation and description (endpoint parameters, validation rules, TTLs and rate limit verified against its diff and config).

QA

Once the backend change is deployed to sandbox, run the documented flow end to end: generate a proof key, authorize via /oauth2/authorize/start, and exchange the code with code_verifier.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• The new and updated code has good coverage.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

Merge only after uphold/backend#19003 is deployed to production, and after #250 merges (this PR is stacked on it). No files removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[ricardobcl]

uphold/backend#19003 has merged (squash fb25dd2d70), so this is now open for review. Keeping the blocked label until that change is deployed to production, since these pages go live on merge and describe the new GET /oauth2/authorize/start endpoint. One follow-up already queued: uphold/backend#19084 forwards intention on the start route — once it lands, intention should be added to the start endpoint's parameter table here.

[ricardobcl]

Description

Documents the Native Application Flow (PKCE) being added to the authorization server by uphold/backend#19003, for native clients (desktop, CLI, mobile) that receive the OAuth redirect on a loopback address — including the MCP client use case.

• New _authentication.md section: proof key generation (code_verifier/code_challenge, S256 only), the GET /oauth2/authorize/start endpoint with its parameters and challenge semantics (30-minute validity, bound to client_id + state, fresh state per attempt), the code_verifier token-exchange parameter with its failure mode (mismatch consumes the code), and loopback redirect URL matching (port-agnostic per RFC 8252 §7.3).
• _applications.md: loopback http redirect URLs are now registrable for native applications, with a pointer to the PKCE requirement they trigger.
• _ratelimits.md: GET /oauth2/authorize/start — 30 requests / 5-min window per IP.
• Intro updated to present the three authorization flows.

Stacked on #250 (the auth-section refresh), since both edit the same sections — this PR targets that branch and will retarget to master automatically when it merges.

Blocked — do not merge until uphold/backend#19003 is merged and deployed

Two open review items on the backend PR may require small wording updates here before merging:

• Whether /oauth2/authorize/start will reject clients that are not PKCE-required (review suggestion) — affects the "other applications may opt in" phrasing.
• Whether client authentication (client_secret) at the token endpoint will be relaxed for public clients — the Step 3 example currently shows -u <clientId>:<clientSecret>, matching today's behavior.

Related issues

• uphold/backend#19003 (blocking)
• Update authentication and rate limit documentation #250 (base branch)

Impacted areas

Authentication, Applications and Rate Limits pages of the API reference.

Steps to reproduce or test

Development

Content derived from the backend PR's implementation and description (endpoint parameters, validation rules, TTLs and rate limit verified against its diff and config).

QA

Once the backend change is deployed to sandbox, run the documented flow end to end: generate a proof key, authorize via /oauth2/authorize/start, and exchange the code with code_verifier.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• The new and updated code has good coverage.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

Merge only after uphold/backend#19003 is deployed to production, and after #250 merges (this PR is stacked on it). No files removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[ricardobcl]

uphold/backend#19003 has merged (squash fb25dd2d70), so this is now open for review. Keeping the blocked label until that change is deployed to production, since these pages go live on merge and describe the new GET /oauth2/authorize/start endpoint. One follow-up already queued: uphold/backend#19084 forwards intention on the start route — once it lands, intention should be added to the start endpoint's parameter table here.

[ricardobcl]

Description

Documents the Native Application Flow (PKCE) being added to the authorization server by uphold/backend#19003, for native clients (desktop, CLI, mobile) that receive the OAuth redirect on a loopback address — including the MCP client use case.

• New _authentication.md section: proof key generation (code_verifier/code_challenge, S256 only), the GET /oauth2/authorize/start endpoint with its parameters and challenge semantics (30-minute validity, bound to client_id + state, fresh state per attempt), the code_verifier token-exchange parameter with its failure mode (mismatch consumes the code), and loopback redirect URL matching (port-agnostic per RFC 8252 §7.3).
• _applications.md: loopback http redirect URLs are now registrable for native applications, with a pointer to the PKCE requirement they trigger.
• _ratelimits.md: GET /oauth2/authorize/start — 30 requests / 5-min window per IP.
• Intro updated to present the three authorization flows.

Stacked on #250 (the auth-section refresh), since both edit the same sections — this PR targets that branch and will retarget to master automatically when it merges.

Blocked — do not merge until uphold/backend#19003 is merged and deployed

Two open review items on the backend PR may require small wording updates here before merging:

• Whether /oauth2/authorize/start will reject clients that are not PKCE-required (review suggestion) — affects the "other applications may opt in" phrasing.
• Whether client authentication (client_secret) at the token endpoint will be relaxed for public clients — the Step 3 example currently shows -u <clientId>:<clientSecret>, matching today's behavior.

Related issues

• uphold/backend#19003 (blocking)
• Update authentication and rate limit documentation #250 (base branch)

Impacted areas

Authentication, Applications and Rate Limits pages of the API reference.

Steps to reproduce or test

Development

Content derived from the backend PR's implementation and description (endpoint parameters, validation rules, TTLs and rate limit verified against its diff and config).

QA

Once the backend change is deployed to sandbox, run the documented flow end to end: generate a proof key, authorize via /oauth2/authorize/start, and exchange the code with code_verifier.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• The new and updated code has good coverage.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

Merge only after uphold/backend#19003 is deployed to production, and after #250 merges (this PR is stacked on it). No files removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[ricardobcl]

uphold/backend#19003 has merged (squash fb25dd2d70), so this is now open for review. Keeping the blocked label until that change is deployed to production, since these pages go live on merge and describe the new GET /oauth2/authorize/start endpoint. One follow-up already queued: uphold/backend#19084 forwards intention on the start route — once it lands, intention should be added to the start endpoint's parameter table here.

[ricardobcl]

Description

Documents the Native Application Flow (PKCE) being added to the authorization server by uphold/backend#19003, for native clients (desktop, CLI, mobile) that receive the OAuth redirect on a loopback address — including the MCP client use case.

• New _authentication.md section: proof key generation (code_verifier/code_challenge, S256 only), the GET /oauth2/authorize/start endpoint with its parameters and challenge semantics (30-minute validity, bound to client_id + state, fresh state per attempt), the code_verifier token-exchange parameter with its failure mode (mismatch consumes the code), and loopback redirect URL matching (port-agnostic per RFC 8252 §7.3).
• _applications.md: loopback http redirect URLs are now registrable for native applications, with a pointer to the PKCE requirement they trigger.
• _ratelimits.md: GET /oauth2/authorize/start — 30 requests / 5-min window per IP.
• Intro updated to present the three authorization flows.

Stacked on #250 (the auth-section refresh), since both edit the same sections — this PR targets that branch and will retarget to master automatically when it merges.

Blocked — do not merge until uphold/backend#19003 is merged and deployed

Two open review items on the backend PR may require small wording updates here before merging:

• Whether /oauth2/authorize/start will reject clients that are not PKCE-required (review suggestion) — affects the "other applications may opt in" phrasing.
• Whether client authentication (client_secret) at the token endpoint will be relaxed for public clients — the Step 3 example currently shows -u <clientId>:<clientSecret>, matching today's behavior.

Related issues

• uphold/backend#19003 (blocking)
• Update authentication and rate limit documentation #250 (base branch)

Impacted areas

Authentication, Applications and Rate Limits pages of the API reference.

Steps to reproduce or test

Development

Content derived from the backend PR's implementation and description (endpoint parameters, validation rules, TTLs and rate limit verified against its diff and config).

QA

Once the backend change is deployed to sandbox, run the documented flow end to end: generate a proof key, authorize via /oauth2/authorize/start, and exchange the code with code_verifier.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• The new and updated code has good coverage.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

Merge only after uphold/backend#19003 is deployed to production, and after #250 merges (this PR is stacked on it). No files removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[ricardobcl]

uphold/backend#19003 has merged (squash fb25dd2d70), so this is now open for review. Keeping the blocked label until that change is deployed to production, since these pages go live on merge and describe the new GET /oauth2/authorize/start endpoint. One follow-up already queued: uphold/backend#19084 forwards intention on the start route — once it lands, intention should be added to the start endpoint's parameter table here.

[ricardobcl]

Description

Documents the Native Application Flow (PKCE) being added to the authorization server by uphold/backend#19003, for native clients (desktop, CLI, mobile) that receive the OAuth redirect on a loopback address — including the MCP client use case.

• New _authentication.md section: proof key generation (code_verifier/code_challenge, S256 only), the GET /oauth2/authorize/start endpoint with its parameters and challenge semantics (30-minute validity, bound to client_id + state, fresh state per attempt), the code_verifier token-exchange parameter with its failure mode (mismatch consumes the code), and loopback redirect URL matching (port-agnostic per RFC 8252 §7.3).
• _applications.md: loopback http redirect URLs are now registrable for native applications, with a pointer to the PKCE requirement they trigger.
• _ratelimits.md: GET /oauth2/authorize/start — 30 requests / 5-min window per IP.
• Intro updated to present the three authorization flows.

Stacked on #250 (the auth-section refresh), since both edit the same sections — this PR targets that branch and will retarget to master automatically when it merges.

Blocked — do not merge until uphold/backend#19003 is merged and deployed

Two open review items on the backend PR may require small wording updates here before merging:

• Whether /oauth2/authorize/start will reject clients that are not PKCE-required (review suggestion) — affects the "other applications may opt in" phrasing.
• Whether client authentication (client_secret) at the token endpoint will be relaxed for public clients — the Step 3 example currently shows -u <clientId>:<clientSecret>, matching today's behavior.

Related issues

• uphold/backend#19003 (blocking)
• Update authentication and rate limit documentation #250 (base branch)

Impacted areas

Authentication, Applications and Rate Limits pages of the API reference.

Steps to reproduce or test

Development

Content derived from the backend PR's implementation and description (endpoint parameters, validation rules, TTLs and rate limit verified against its diff and config).

QA

Once the backend change is deployed to sandbox, run the documented flow end to end: generate a proof key, authorize via /oauth2/authorize/start, and exchange the code with code_verifier.

Checklist

• Add label Breaking Change if it applies.
• Commits are atomic and logically separated.
• Performance implications have been considered.
• Security implications have been considered.
• The new and updated code has good coverage.
• API documentation, if required, has been created or updated.
• New dependencies have been added to package.json.
• The README file, if required, has been updated.
• Architectural diagram, if required, has been updated.

Deploy notes

Merge only after uphold/backend#19003 is deployed to production, and after #250 merges (this PR is stacked on it). No files removed, so no slate index changes are needed.

🤖 Generated with Claude Code

[ricardobcl]

uphold/backend#19003 has merged (squash fb25dd2d70), so this is now open for review. Keeping the blocked label until that change is deployed to production, since these pages go live on merge and describe the new GET /oauth2/authorize/start endpoint. One follow-up already queued: uphold/backend#19084 forwards intention on the start route — once it lands, intention should be added to the start endpoint's parameter table here.