Skip to content
Fandation API Documentation

Authentication

Fandation’s documented API integration uses OAuth 2.0 Authorization Code with PKCE.

Scope

Section titled “Scope”

Registered partner applications can request this scope:

documents:read

The scope grants read-only access to the user’s published Fandation documents.

Authorization flow

Section titled “Authorization flow”
sequenceDiagram
    participant User
    participant Partner as Partner application
    participant Fandation

    Partner->>Partner: Generate state and PKCE values
    Partner->>Fandation: Create authorization request
    Fandation-->>Partner: Return authorization URL
    Partner-->>User: Redirect browser to Fandation
    User->>Fandation: Authenticate and complete setup, if needed
    Fandation->>User: Request document access
    User->>Fandation: Approve access
    Fandation-->>Partner: Redirect callback with code and state
    Partner->>Partner: Validate state
    Partner->>Fandation: Exchange code and PKCE verifier
    Fandation-->>Partner: Return access token
    Partner->>Fandation: Request published documents
    Fandation-->>Partner: Return published documents

At a glance:

  1. The partner application generates unique state and PKCE values.
  2. The partner backend creates an authorization request and redirects the user to Fandation.
  3. The user completes any required authentication or setup and approves document access.
  4. Fandation redirects to the registered partner callback with an authorization code and the original state.
  5. The partner validates the state and exchanges the code and PKCE verifier for an access token.
  6. The partner uses the access token to request the user’s published documents.

Client credentials

Section titled “Client credentials”

Fandation provides a registered OAuth client with:

client_id
client_secret
registered redirect URI

The redirect URI used during authorization and token exchange must exactly match a registered redirect URI. Keep the client secret in the partner application’s backend and don’t expose it in browser code or source control.

State and PKCE

Section titled “State and PKCE”

Generate a unique state, code_verifier, and code_challenge for the authorization flow. Use S256 as the code_challenge_method.

Store the state, code_verifier, and the user’s original location in the partner application until the callback completes. When Fandation redirects to the callback, validate that the returned state matches the stored value before exchanging the authorization code.

Access tokens

Section titled “Access tokens”

Exchange the authorization code and PKCE verifier at the token endpoint. Use the returned short-lived access token as a Bearer token when requesting documents. Fetch documents before the access token expires.

Continue with the OAuth integration guide for the complete flow, or see the OAuth and documents API reference for request and response formats.