docs: add PKCE OAuth2 guide for public clients#113
docs: add PKCE OAuth2 guide for public clients#113blink-claw-bot wants to merge 1 commit intoblinkbitcoin:mainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new documentation section describing how to integrate with Blink OAuth2 as a public client using the Authorization Code + PKCE flow (for mobile apps, SPAs, and CLIs that can’t keep a client secret).
Changes:
- Added a “Public Clients (PKCE)” section explaining when/how to use PKCE and the end-to-end flow.
- Included PKCE curl examples, mobile implementation notes (deep links, storage), and security considerations.
- Updated “Client ID and Secret” to clarify that public clients receive only a Client ID and should use PKCE.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - The OS automatically routes the redirect back to your app — no backend server needed | ||
|
|
||
| #### Secure Token Storage | ||
| - **iOS:** Store tokens in the iOS Keychain using `keychain-services` |
There was a problem hiding this comment.
The iOS guidance references keychain-services, which reads like a library/package name but isn’t a standard iOS API. To avoid confusing integrators, consider rephrasing to the platform API name (Keychain Services / Keychain) or linking to an actual, commonly used library if that’s what you intend.
| - **iOS:** Store tokens in the iOS Keychain using `keychain-services` | |
| - **iOS:** Store tokens in the iOS Keychain (Keychain Services) |
| -d "redirect_uri=cypherbox://auth/callback" \ | ||
| -d "client_id=$YOUR_CLIENT_ID" \ | ||
| -d "code_verifier=$CODE_VERIFIER" |
There was a problem hiding this comment.
The curl example uses -d "redirect_uri=cypherbox://auth/callback" (and other params) as a raw form field. For strict application/x-www-form-urlencoded compliance and to avoid subtle encoding issues with redirect URIs/verifiers, use --data-urlencode for fields like redirect_uri (and ideally code_verifier).
| -d "redirect_uri=cypherbox://auth/callback" \ | |
| -d "client_id=$YOUR_CLIENT_ID" \ | |
| -d "code_verifier=$CODE_VERIFIER" | |
| --data-urlencode "redirect_uri=cypherbox://auth/callback" \ | |
| -d "client_id=$YOUR_CLIENT_ID" \ | |
| --data-urlencode "code_verifier=$CODE_VERIFIER" |
| -d "grant_type=refresh_token" \ | ||
| -d "refresh_token=$REFRESH_TOKEN" \ | ||
| -d "client_id=$YOUR_CLIENT_ID" |
There was a problem hiding this comment.
Similarly, the refresh token curl example uses raw -d fields. Using --data-urlencode (especially for refresh_token, which can include characters needing encoding) will make the example more robust across shells and clients.
| -d "grant_type=refresh_token" \ | |
| -d "refresh_token=$REFRESH_TOKEN" \ | |
| -d "client_id=$YOUR_CLIENT_ID" | |
| --data-urlencode "grant_type=refresh_token" \ | |
| --data-urlencode "refresh_token=$REFRESH_TOKEN" \ | |
| --data-urlencode "client_id=$YOUR_CLIENT_ID" |
Adds documentation for integrating with Blink OAuth2 using PKCE (Proof Key for Code Exchange) for public clients — mobile apps, SPAs, and CLI tools that can't safely store a client secret.
Changes
Context
Cypherbox (mobile Bitcoin app) wants to integrate with Blink OAuth2 but has no backend server. PKCE enables the full OAuth2 Authorization Code flow client-side without needing a client secret. Blink's Hydra server supports this natively — it just requires registering the client as a public client (
token_endpoint_auth_method: none).References: