Skip to main content
Status: DraftCreated: 2025-02-13Updated: 2025-02-13

​
Overview

The Platform API enables partners to create and manage Polar Organizations on behalf of their users, allowing seamless integration of monetization features into third-party platforms. This document outlines the technical architecture, authentication flow, and claim process for the Platform API.

​
Core Entities

​
Platform Entity

A new Platform entity will be introduced to represent partners with access to the Platform API:
  • Purpose: Represents external platforms that can create and manage Organizations
  • Key attributes:
    • id: Unique identifier for the Platform
    • name: Human-readable name of the platform
    • jwks_url: URL where the platform exposes its JWKS (JSON Web Key Set)
    • created_at: Timestamp of platform creation
    • updated_at: Timestamp of last update

​
Organization Enhancements

The existing Organization entity will be enhanced with platform-specific fields:
  • New fields:
    • platform_id (nullable): Foreign key to the Platform that created/owns this Organization
    • platform_external_id (nullable): The Organization’s ID on the external platform
    • platform_created_at (nullable): Timestamp when the Organization was created via Platform API

​
Authentication Flow

​
OIDC-based Authentication

The Platform API uses an OIDC approach with JWT tokens for authentication:
  1. Platform Setup: Partner exposes JWKS at a public URL
  2. JWT Creation: Platform creates a JWT signed with their private key
  3. Token Exchange: JWT is sent to Polar’s OAuth2 token endpoint
  4. Validation: Polar validates the JWT using the platform’s public key
  5. Access Token: Polar returns an Organization Access Token

​
JWT Structure

We support two types of JWTs for different use cases:

​
Organization JWT (for Organization Access Tokens)

Used when the platform wants to act on behalf of a specific organization: 
{
  "jti": "org-token-id-12345", // Unique ID for the token (single use)
  "sub": "org-external-123", // Platform's external organization ID
  "iss": "platform-123", // Platform ID
  "aud": "polar:platform-organization", // Audience: organization operations
  "organization_name": "Acme Inc", // Optional: Organization name (creation only)
  "organization_slug": "acme", // Optional: Organization slug (creation only)
  "iat": 1735689600, // Issued at timestamp
  "nbf": 1735689600, // Not before timestamp
  "exp": 1735776000 // Expiration timestamp
}

​
Platform JWT (for Platform Access Tokens)

Used when the platform wants to perform platform-level operations: 
{
  "jti": "platform-token-id-67890", // Unique ID for the token
  "sub": "platform-123", // Platform ID (subject)
  "iss": "platform-123", // Platform ID (issuer)
  "aud": "polar:platform", // Audience: platform operations
  "iat": 1735689600, // Issued at timestamp
  "nbf": 1735689600, // Not before timestamp
  "exp": 1735776000 // Expiration timestamp
}
Key Differences:
  • Organization JWT: Contains organization-specific claims (sub = org external ID)
  • Platform JWT: Contains only platform claims (sub = iss = platform ID)
  • Audience: Different aud values determine token type

​
Token Validation Process

The validation process differs based on the JWT type:

​
Organization JWT Validation

  1. JWT Validation: Verify signature using platform’s JWKS
  2. Audience Check: Ensure aud = polar:platform-organization
  3. Claim Extraction: Extract sub (platform_external_id) and iss (platform_id)
  4. Organization Lookup: Query Organization by platform_external_id and platform_id
  5. Organization Creation (if not exists):
    • Create new Organization using organization_name and organization_slug from JWT
    • Set platform_id and platform_external_id
  6. Access Token Issuance: Return Organization Access Token

​
Platform JWT Validation

  1. JWT Validation: Verify signature using platform’s JWKS
  2. Audience Check: Ensure aud = polar:platform
  3. Claim Validation: Ensure sub = iss = platform_id
  4. Platform Verification: Verify platform exists and is active
  5. Access Token Issuance: Return Platform Access Token with requested scopes

​
Organization Claim Flow

​
Purpose

The claim flow allows a User to take ownership of an Organization created via the Platform API, enabling KYC completion and financial setup.

​
Process

  1. Claim Token Generation:
    • Platform calls /api/platform/organizations/{platform_external_id}/claim_token
    • Polar generates a short-lived, single-use claim token
    • Token contains: organization_id, platform_id, expiration
  2. User Onboarding:
    • Platform presents claim token to their user
    • User visits Polar’s onboarding flow with claim token
    • User creates Polar account (or logs in)
  3. Organization Claiming:
    • User submits claim token during onboarding
    • Polar validates token and links User to Organization
  4. Post-Claim Process:
    • User completes KYC verification
    • User sets up financial/payout details
    • Organization becomes fully active

​
Platform Access Tokens

​
Overview

In addition to Organization Access Tokens, we introduce Platform Access Tokens that allow platforms to manage multiple organizations and perform platform-level operations.

​
Platform JWT Structure

Platforms can authenticate using a dedicated Platform JWT: 
{
  "jti": "platform-token-id-67890", // Unique ID for the token
  "sub": "platform-123", // Platform ID (subject)
  "iss": "platform-123", // Platform ID (issuer)
  "aud": "polar:platform", // Audience: platform operations
  "iat": 1735689600, // Issued at timestamp
  "nbf": 1735689600, // Not before timestamp
  "exp": 1735776000 // Expiration timestamp
}
Key differences from Organization JWT:
  • sub and iss are both the Platform ID
  • aud is polar:platform (vs polar:platform-organization for org-specific operations)
  • No organization-specific claims

​
Platform Access Token Capabilities

Platform Access Tokens enable:
  • Listing all organizations created by the platform
  • Generating claim tokens for any platform organization
  • Accessing platform-level analytics and reporting
  • Managing platform configuration

​
Token Exchange for Platform Access

curl -X POST https://api.polar.sh/v1/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "platform",
    "oidc_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

​
API Endpoints

​
Platform Authentication

  • POST /v1/oauth2/token - Exchange JWT for access tokens
    • grant_type: platform with aud: polar:platform → Platform Access Token
    • grant_type: platform with aud: polar:platform-organization → Organization Access Token

​
Organization Management (Platform Access)

  • GET /api/platform/organizations/ - List all platform organizations (requires Platform Access Token)
  • GET /api/platform/organizations/{platform_external_id} - Get organization by external ID
  • POST /api/platform/organizations/{platform_external_id}/claim_token - Generate claim token

​
Organization Management (Organization Access)

  • Standard Polar API endpoints (products, customers, subscriptions, etc.)

​
Appendix: Sandbox as a Platform

Maybe a crazy idea, but we could consider the Polar Sandbox as a Platform on the Production environment. This would enable us to implement processes to automatically create an Organization in Production from a Sandbox!