OAuth integration

Fandation OAuth lets your application request access to a user’s published Fandation documents.

The integration uses OAuth 2.0 Authorization Code with PKCE.

Before you begin

Document access through OAuth is available to registered Fandation integration partners.

Complete partner onboarding first

Register the integration and receive an approved OAuth client by completing partner onboarding before implementing or testing this flow.

After Fandation confirms that the OAuth client is ready, continue with the authorization flow below.

Scope

documents:read

Refresh tokens aren’t currently supported.

Integration flow

1. Generate a state value and PKCE verifier in the partner application.
2. Create an authorization request with Fandation.
3. Redirect the user to the returned authorization URL.
4. If needed, the user signs in or creates a Fandation account, then completes setup and approves access.
5. Fandation redirects to the registered partner callback with a code and state.
6. Validate the state, then exchange the code and PKCE verifier for an access token.
7. Use the access token to request the user’s published documents.

1. Configure your OAuth client

Store the values provided by Fandation in your backend configuration:

client_id
client_secret
registered redirect URI

Keep the client secret confidential. The redirect URI used during authorization and token exchange must exactly match a registered redirect URI.

2. Generate state and PKCE values

Generate:

state
code_verifier
code_challenge

Use PKCE with:

code_challenge_method=S256

Store the state, code_verifier, and the user’s original location in your application until the callback completes.

3. Create an authorization request

Send the authorization request described in the API reference, then redirect the user’s browser to the returned authorizationUrl.

4. Handle the callback

After approval, Fandation redirects to the registered redirect URI:

https://partner.example.com/oauth/callback?code=AUTHORIZATION_CODE&state=opaque-partner-state

Validate that the returned state matches the value created by your application.

The callback contains only:

code
state

Use the state stored by your application to restore the user’s original location or workflow.

5. Exchange the authorization code

Exchange the code using the token request. The response contains a short-lived Bearer access token.

6. Request documents

Use the token to list published documents or get one document.

Authorization errors

When authorization is denied or can’t be completed, Fandation redirects to the registered callback with standard OAuth error parameters:

error
error_description
state

Important behavior

• Access tokens are short-lived.
• Refresh tokens aren’t issued in version one.
• Only published document content is returned.
• Fetch documents immediately after the callback.
• The partner application is responsible for restoring its own workflow using state.