Skip to content

API Reference ​

Sesamy provides comprehensive REST APIs for managing content monetization, subscriptions, and user data.

API Overview ​

Sesamy offers two main API groups:

Client API ​

For end-user facing operations and content access control.

Base URL: https://api2.sesamy.com

Use cases:

  • User authentication and profiles
  • Content access verification
  • Subscription management
  • Payment processing
  • Entitlement checks
  • Leaky paywall access (metered free articles)

BFF / Token Handler auth endpoints ​

The Client API also exposes the cookie-based (BFF) auth flow. The vendor ID is embedded in the path so that no hostname configuration is required:

EndpointDescription
GET /auth/:vendorId/loginStarts the PKCE authorization flow — redirects to the auth server
GET /auth/:vendorId/callbackHandles the OAuth callback, exchanges the code, sets HttpOnly cookies
GET /auth/:vendorId/logoutClears auth cookies; optionally performs federated logout (GET /auth/logout is still accepted but relies on the client hint cookie)
GET /auth/userinfoReturns { authenticated, sub, exp } without exposing tokens

See BFF Authentication for the full guide.

Explore Client API →

Management API ​

For administrative operations and backend management.

Base URL: https://api2.sesamy.com/management

Authentication: OAuth 2.0 Client Credentials flow with scopes

Use cases:

  • User management
  • Vendor configuration (including BFF/Token Handler settings via PUT /management/vendors/:vendorId/token-handler)
  • Product and pricing management
  • Analytics and reporting
  • Bulk operations
  • Access lists and grants management

Required Permissions: Various scopes depending on the resource (e.g., users:read, users:write, access-lists:read, access-lists:write)

Learn more about Management API Permissions →

Explore Management API →

Discover purchase options ​

With the products:read scope, GET /management/products and GET /management/products/{sku} return purchaseOptions for each product. Use an option's id as items[].purchaseOptionId in the Partner Checkout quote/checkout request, together with the product's sku. The list returns an array; the single-product endpoint returns an object such as:

json
{
  "sku": "sid:acme-plus",
  "title": "ACME Plus",
  "productType": "bundle",
  "cover": "https://acme.example.com/cover.png",
  "language": "sv",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "purchaseOptions": [
    {
      "id": "acme-monthly",
      "title": "Monthly subscription",
      "purchaseType": "RECURRING",
      "prices": [
        {
          "market": "SE",
          "currency": "SEK",
          "amount": 149,
          "amountExcludingTax": 140.57,
          "tax": 8.43
        }
      ],
      "recurring": { "interval": "MONTH", "intervalCount": 1 },
      "isForSale": true,
      "isListed": true
    }
  ]
}

Prices are listed per market in major units of the currency (149 is 149.00 SEK), with tax included in amount. recurring says how often a RECURRING option is billed; lease options use duration for how long access lasts, and per-issue options give issues. License products can include seatsPerUnit, minQuantity, and maxQuantity.

isForSale is false when you have stopped sales of an option, and isListed is false for an option hidden from listings. Quote and checkout still check the product's availability and the buyer's market, so isForSale: true does not guarantee that a purchase succeeds. A product without options has purchaseOptions: [].

API Fundamentals ​

Base URLs ​

EnvironmentClient APIManagement API
Productionhttps://api2.sesamy.comhttps://api2.sesamy.com/management
Staginghttps://staging-api.sesamy.comhttps://staging-api.sesamy.com/management

Vendor Hosts ​

A vendor whose ID is a valid DNS label (1 to 63 lowercase letters, digits, or hyphens, not starting or ending with a hyphen) can also call both APIs on its own host, https://<vendorId>.api.sesamy.com. For a vendor with the ID acme:

Client APIManagement API
https://acme.api.sesamy.comhttps://acme.api.sesamy.com/management

The paths, authentication, and responses are the same as on api2.sesamy.com. The host names the vendor, so anonymous requests don't need a Vendor-Id header.

A vendor host only serves its own vendor. The API rejects a request with status 403 when the vendor it resolves from your credentials, or the vendor in a Vendor-Id header or vendor-id query parameter, differs from the host's. The body is plain text:

text
The request vendor does not match the vendor host

Credentials are checked first: a request without a token to a route that needs one gets 401 before the vendor is compared. Requests to api2.sesamy.com are never checked this way.

Request Format ​

All API requests must include a valid JWT token in the Authorization header. The JWT contains tenant information and permissions.

bash
curl -X GET https://api2.sesamy.com/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

The JWT token includes:

  • Tenant ID: Identifies which tenant/vendor the request is for
  • Permissions: Defines what actions the request is authorized to perform

Response Format ​

All responses are in JSON format:

json
{
  "data": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "meta": {
    "timestamp": "2025-10-28T10:30:00Z"
  }
}

Error Responses ​

Errors follow a consistent format:

json
{
  "error": {
    "code": "validation_error",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}

Common Patterns ​

Pagination ​

List endpoints support pagination:

bash
curl -X GET "https://api2.sesamy.com/transactions?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response includes pagination metadata:

json
{
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Filtering ​

Filter results with query parameters:

bash
curl -X GET "https://api2.sesamy.com/subscriptions?status=active&product=prod_123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Sorting ​

Sort results using the sort parameter:

bash
curl -X GET "https://api2.sesamy.com/transactions?sort=-created_at" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Use - prefix for descending order.

HTTP Status Codes ​

CodeDescription
200Success
201Created
204No Content
400Bad Request
401Unauthorized
403Forbidden
404Not Found
429Too Many Requests
500Internal Server Error

Versioning ​

The API does not include a version in the URL path. We maintain backward compatibility and provide advance notice of breaking changes.

Example endpoints:

  • Client API: https://api2.sesamy.com/profile
  • Management API: https://api2.sesamy.com/management/users

Rate Limits ​

See Rate Limits for detailed information.

Error Handling ​

See Error Handling for comprehensive error handling guides.

OpenAPI Specification ​

Access the complete OpenAPI specifications:

Interactive API Explorer ​

Try the APIs in your browser:

Next Steps ​

Released under the MIT License.