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:
| Endpoint | Description |
|---|---|
GET /auth/:vendorId/login | Starts the PKCE authorization flow — redirects to the auth server |
GET /auth/:vendorId/callback | Handles the OAuth callback, exchanges the code, sets HttpOnly cookies |
GET /auth/:vendorId/logout | Clears auth cookies; optionally performs federated logout (GET /auth/logout is still accepted but relies on the client hint cookie) |
GET /auth/userinfo | Returns { authenticated, sub, exp } without exposing tokens |
See BFF Authentication for the full guide.
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 →
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:
{
"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
| Environment | Client API | Management API |
|---|---|---|
| Production | https://api2.sesamy.com | https://api2.sesamy.com/management |
| Staging | https://staging-api.sesamy.com | https://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 API | Management API |
|---|---|
https://acme.api.sesamy.com | https://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:
The request vendor does not match the vendor hostCredentials 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.
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:
{
"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:
{
"error": {
"code": "validation_error",
"message": "Invalid email format",
"details": {
"field": "email",
"value": "invalid-email"
}
}
}Common Patterns
Pagination
List endpoints support pagination:
curl -X GET "https://api2.sesamy.com/transactions?limit=20&offset=0" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Response includes pagination metadata:
{
"data": [...],
"pagination": {
"total": 150,
"limit": 20,
"offset": 0,
"hasMore": true
}
}Filtering
Filter results with query parameters:
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:
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
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 204 | No Content |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal 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
- Client API - End-user operations
- Management API - Administrative operations
- Rate Limits - Understand rate limiting
- Error Handling - Handle errors gracefully