Skip to content

Conversation

@nicknisi
Copy link
Member

@nicknisi nicknisi commented Oct 28, 2025

Summary

Fixes #326

The state parameter in getSignInUrl/getSignUpUrl is implemented as a string (matching OAuth 2.0 RFC 6749 specification), but the documentation showed examples using object literals without JSON serialization. This created a mismatch between what the docs promised and what actually works.

Changes

Updated all documentation examples to show explicit serialization:

  1. Type documentation (line 141): Changed from Record<string, any> | undefined to string | undefined with parsing note
  2. Early callback example (lines 103-105): Added JSON.parse(state) before accessing properties
  3. Inline sign-in example (lines 227-232): Added JSON.stringify() around state object
  4. Full "Passing Custom State" section (lines 405-445):
    • Updated intro to explain state is a string per OAuth spec
    • Added JSON.stringify() to all examples
    • Added JSON.parse() with null checks in callbacks
    • Added RFC 6749 reference explaining why serialization is manual

Why This Approach

The implementation correctly follows OAuth 2.0 RFC 6749, which defines state as an "opaque string". Keeping it as a string gives users control over serialization format (JSON, base64, encrypted tokens, etc.) and matches the WorkOS SDK interface.

The state parameter in getSignInUrl/getSignUpUrl is implemented as a
string (matching OAuth 2.0 RFC 6749 specification), but the documentation
showed examples using object literals without JSON serialization.

This commit updates all documentation examples to:
- Show explicit JSON.stringify() when passing state objects
- Show explicit JSON.parse() when reading state in callbacks
- Update the type table to reflect string | undefined instead of Record<string, any>
- Add a note explaining that state is an opaque string per OAuth 2.0 spec

Fixes #326
@nicknisi nicknisi merged commit cfaef3f into main Oct 29, 2025
4 checks passed
@nicknisi nicknisi deleted the fix/state-parameter-docs branch October 29, 2025 22:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

getSignInUrl state type doesn't align with the docs

3 participants