Skip to content
Fandation API Documentation

OAuth and documents API

This reference covers the endpoints documented for the Fandation OAuth integration. Fandation doesn’t currently provide an OpenAPI document in this repository, so this reference is maintained as Markdown.

Endpoints

Section titled “Endpoints”
Authorization request:
POST https://app.fandation.com/api/v1/oauth/authorization-requests


Authorization:
GET https://app.fandation.com/oauth/authorize


Token:
POST https://app.fandation.com/oauth/token


Documents:
GET https://app.fandation.com/api/v1/documents
GET https://app.fandation.com/api/v1/documents/{embedKey}

Create an authorization request

Section titled “Create an authorization request”
POST /api/v1/oauth/authorization-requests
Authorization: Basic BASE64_CLIENT_ID_AND_CLIENT_SECRET
Content-Type: application/json

Example request:

{
  "redirectUri": "https://partner.example.com/oauth/callback",
  "state": "opaque-partner-state",
  "scope": "documents:read",
  "codeChallenge": "PKCE_CODE_CHALLENGE",
  "codeChallengeMethod": "S256",
  "externalReference": "partner-record-123",
  "artist": {
    "platform": "spotify",
    "platformId": "4Z8W4fKeB5YxbusRsdQVPb",
    "name": "Example Artist"
  }
}

Example response:

{
  "authorizationUrl": "https://app.fandation.com/oauth/authorize?request_id=fnd_req_abc123",
  "expiresIn": 900
}

Redirect the user’s browser to authorizationUrl.

Exchange an authorization code

Section titled “Exchange an authorization code”
POST /oauth/token
Authorization: Basic BASE64_CLIENT_ID_AND_CLIENT_SECRET
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fpartner.example.com%2Foauth%2Fcallback
&code_verifier=PKCE_CODE_VERIFIER

Example response:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "documents:read"
}

List published documents

Section titled “List published documents”
GET /api/v1/documents
Authorization: Bearer ACCESS_TOKEN

Optional query parameters:

documentType
languageCode
contentView

Example:

GET /api/v1/documents?documentType=privacy_policy&languageCode=en
Authorization: Bearer ACCESS_TOKEN

Get one document

Section titled “Get one document”
GET /api/v1/documents/{embedKey}
Authorization: Bearer ACCESS_TOKEN

embedKey is the external document identifier.

Document response

Section titled “Document response”
{
  "documents": [
    {
      "embedKey": "9dd9b24d-5d20-4e31-aa47-d84c8bfcad6c",
      "documentType": "privacy_policy",
      "name": "Privacy Policy",
      "isVariant": false,
      "parentEmbedKey": null,
      "defaultLanguageCode": "en",
      "languageCode": "en",
      "availableLanguages": ["en"],
      "content": {
        "html": "<h1>Privacy Policy</h1>",
        "text": "Privacy Policy"
      },
      "variants": []
    }
  ]
}

A single-document response uses:

{
  "document": {}
}