Skip to content

OpenAPI Specification ​

Servers​

https://api2.sesamy.comCurrent environment

Check content access without recording a read​

POST
/content/has-access

Returns a boolean. Resolves fixed paywalls and strategies internally. The legacy media type preserves sesamy-js entitlement/boolean/null results during migration. The content-access media type also returns the selected paywall and, when a strategy chose it, the decisionId and strategyId.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"attribution": {
  
  
"source": "google",
  
  
"medium": "cpc",
  
  
"campaign": "summer_sale",
  
  
"term": "running shoes",
  
  
"content": "logolink",
  
  
"referrer": "https://www.google.com/"
  
},
  
"content": {
  
  
"contentId": "string",
  
  
"title": "string",
  
  
"type": "string",
  
  
"price": 0,
  
  
"currency": "string",
  
  
"publisherId": "string",
  
  
"contentType": "NewsArticle",
  
  
"section": "sports",
  
  
"tags": [
  
  
  
[
  
  
  
  
"football",
  
  
  
  
"premier-league"
  
  
  
]
  
  
],
  
  
"authors": [
  
  
  
[
  
  
  
  
"Jane Doe"
  
  
  
]
  
  
],
  
  
"publishedAt": "2026-01-15T09:00:00.000Z"
  
},
  
"accessLevel": "string",
  
"publisherContentId": "string",
  
"url": "string",
  
"paywall": "string",
  
"passes": [
  
  
"string"
  
]
}

Responses​

Non-consuming access decision

JSON
true

Playground​

Authorization
Body

Samples​


Authorize content delivery and register a successful read​

POST
/content/unlock

Resolves policies internally. Capsule verifies its signed descriptor before returning keys; proxy grants retain legacy token authorization. Local encoded delivery returns only a decision, never a reusable token or key. DCA delivery answers a publisher-sealed Delegated Content Access request (e.g. Labrador) addressed to issuer "sesamy": it verifies the publisher's resourceJWT against the vendor's registered publishers and returns the opened content keys the reader may use.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"attribution": {
  
  
"source": "google",
  
  
"medium": "cpc",
  
  
"campaign": "summer_sale",
  
  
"term": "running shoes",
  
  
"content": "logolink",
  
  
"referrer": "https://www.google.com/"
  
},
  
"content": {
  
  
"contentId": "string",
  
  
"title": "string",
  
  
"type": "string",
  
  
"price": 0,
  
  
"currency": "string",
  
  
"publisherId": "string",
  
  
"contentType": "NewsArticle",
  
  
"section": "sports",
  
  
"tags": [
  
  
  
[
  
  
  
  
"football",
  
  
  
  
"premier-league"
  
  
  
]
  
  
],
  
  
"authors": [
  
  
  
[
  
  
  
  
"Jane Doe"
  
  
  
]
  
  
],
  
  
"publishedAt": "2026-01-15T09:00:00.000Z"
  
},
  
"accessLevel": "string",
  
"publisherContentId": "string",
  
"url": "string",
  
"paywall": "string",
  
"passes": [
  
  
"string"
  
],
  
"delivery": "string"
}

Responses​

Delivery authorization or selected paywall

application/json
JSON
{
  
"status": "string",
  
"reason": "string",
  
"token": "string",
  
"paywallId": "string",
  
"paywall": {
  
  
"id": "aM8o7LqpkGZJ-szyPwe_E",
  
  
"vendorId": "acme",
  
  
"currency": "SEK",
  
  
"version": 2,
  
  
"settings": {
  
  
  
"template": "BOXES",
  
  
  
"useDefaultLogo": true,
  
  
  
"useDefaultCurrency": true,
  
  
  
"useDefaultColor": true,
  
  
  
"styling": {
  
  
  
  
"dropShadow": true,
  
  
  
  
"backgroundColor": "#000000",
  
  
  
  
"showBackground": false
  
  
  
},
  
  
  
"displayOptions": {
  
  
  
  
"enableGift": true,
  
  
  
  
"enableCompany": true,
  
  
  
  
"enableLoginButton": true
  
  
  
},
  
  
  
"loginFields": {
  
  
  
  
"name": true
  
  
  
},
  
  
  
"leaky": {
  
  
  
  
"enabled": true,
  
  
  
  
"count": 3,
  
  
  
  
"periodInHours": 720
  
  
  
},
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
"redirectLabel": "Go to ACME",
  
  
  
"showPricesExVat": false
  
  
},
  
  
"showLoginButton": true,
  
  
"subscriptions": [
  
  
  
{
  
  
  
  
"id": "R4gX0YSbSU1WJA7bCrbQw",
  
  
  
  
"sku": "sid:acme-plus-monthly",
  
  
  
  
"poId": "VDuH_poxqIPKW638Ok43q",
  
  
  
  
"title": "ACME Plus monthly",
  
  
  
  
"description": "<p>Only 720 kr/year - save 20%</p>",
  
  
  
  
"price": 99,
  
  
  
  
"discountPrice": 75,
  
  
  
  
"discountCode": "WELCOME20",
  
  
  
  
"periodText": "3 months",
  
  
  
  
"comparePeriodText": "month",
  
  
  
  
"tag": "Most popular",
  
  
  
  
"selected": true,
  
  
  
  
"features": [
  
  
  
  
  
[
  
  
  
  
  
  
"Daily news",
  
  
  
  
  
  
"Exclusive interviews"
  
  
  
  
  
]
  
  
  
  
],
  
  
  
  
"buttonText": "BUY ACCESS",
  
  
  
  
"readMoreLink": "https://acme.example.com/subscriptions",
  
  
  
  
"readMoreText": "Read more",
  
  
  
  
"preferBusiness": false,
  
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
  
"redirectLabel": "Start reading ACME Plus",
  
  
  
  
"discountId": "disc_acme_welcome",
  
  
  
  
"priceMode": "AUTOMATIC",
  
  
  
  
"url": "https://acme.example.com/business",
  
  
  
  
"pricePeriod": {
  
  
  
  
  
"period": "month",
  
  
  
  
  
"time": 3
  
  
  
  
},
  
  
  
  
"discountPeriod": {
  
  
  
  
  
"period": "month",
  
  
  
  
  
"time": 3
  
  
  
  
},
  
  
  
  
"discountMonths": 6,
  
  
  
  
"trialDays": 14
  
  
  
}
  
  
],
  
  
"subscriptionsUrl": "https://acme.example.com/subscriptions.json",
  
  
"features": [
  
  
  
[
  
  
  
  
"Everything on acme.example.com"
  
  
  
]
  
  
],
  
  
"mainColor": "#3377fe",
  
  
"headline": "Get access to ACME Plus",
  
  
"description": "<p>Read every article, on every device.</p>",
  
  
"logoUrl": "https://assets.sesamy.com/vendor-assets/acme/logo.svg",
  
  
"footerPaymentMethods": [
  
  
  
[
  
  
  
  
"visa",
  
  
  
  
"mastercard",
  
  
  
  
"google-pay",
  
  
  
  
"apple-pay"
  
  
  
]
  
  
],
  
  
"singlePurchase": {
  
  
  
"enabled": true,
  
  
  
"title": "Buy Now",
  
  
  
"description": "One-time purchase",
  
  
  
"discountCode": "WELCOME20",
  
  
  
"discountId": "disc_acme_welcome"
  
  
},
  
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
  
"strategyId": "st_abc123"
  
},
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
"strategyId": "st_abc123"
}

Playground​

Authorization
Body

Samples​


Proxy content​

GET
/proxy

Proxies content from supported providers, optionally extracting specific elements.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

url*

The URL of the content to proxy

Type
string
Required
Example"https://www.example.com/article"
selector

Optional CSS selector to extract specific element from the page

Type
string
Example".article-content"
cache

Whether to use cache (set to "false" to bypass cache)

Type
string
Example"true"

Responses​

The unlocked content

text/html
JSON
"string"

Playground​

Authorization
Variables
Key
Value

Samples​


List all contracts​

GET
/contracts

Retrieves all contracts for the current user. Includes subscription plans and one-time purchases with active entitlements.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

A list of the user's contracts

application/json
JSON
[
  
{
  
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
  
"name": "string",
  
  
"userId": "string",
  
  
"payer": {
  
  
  
"id": "string",
  
  
  
"email": "string"
  
  
},
  
  
"createdAt": "string",
  
  
"confirmedAt": "string",
  
  
"updatedAt": "string",
  
  
"price": 0,
  
  
"nextBillAt": "string",
  
  
"nextPrice": 0,
  
  
"currency": "string",
  
  
"manageUrl": "string",
  
  
"contractDuration": "string",
  
  
"issuesRemaining": 0,
  
  
"items": [
  
  
  
{
  
  
  
  
"id": "string",
  
  
  
  
"sku": "string",
  
  
  
  
"purchaseOptionId": "string",
  
  
  
  
"purchaseOptionName": "string",
  
  
  
  
"name": "string",
  
  
  
  
"cover": "string",
  
  
  
  
"productType": "string",
  
  
  
  
"purchaseType": "string",
  
  
  
  
"isMultiseat": true,
  
  
  
  
"quantity": 0,
  
  
  
  
"seats": 0
  
  
  
}
  
  
],
  
  
"status": "string",
  
  
"isActive": true,
  
  
"recurringInterval": "string",
  
  
"recurringTime": 0,
  
  
"recurringPrice": [
  
  
  
{
  
  
  
  
"from": "string",
  
  
  
  
"to": "string",
  
  
  
  
"id": "string",
  
  
  
  
"price": 0,
  
  
  
  
"currency": "string",
  
  
  
  
"interval": "string",
  
  
  
  
"intervalCount": 0,
  
  
  
  
"discount": {
  
  
  
  
  
"amount": 0,
  
  
  
  
  
"percentage": 0,
  
  
  
  
  
"fullPrice": 0,
  
  
  
  
  
"codes": [
  
  
  
  
  
  
{
  
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
  
"amount": 0
  
  
  
  
  
  
}
  
  
  
  
  
]
  
  
  
  
}
  
  
  
}
  
  
],
  
  
"willCancelAt": "string",
  
  
"cancelRequestedAt": "string",
  
  
"canceledAt": "string",
  
  
"cancelReason": "string",
  
  
"expiresAt": "string",
  
  
"origin": {
  
  
  
"type": "string",
  
  
  
"id": "string"
  
  
},
  
  
"paymentData": {
  
  
  
"method": "string",
  
  
  
"description": "string",
  
  
  
"brand": "string",
  
  
  
"walletType": "string"
  
  
},
  
  
"appliedDiscounts": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"name": "string",
  
  
  
  
"description": "string",
  
  
  
  
"id": "string",
  
  
  
  
"status": "string",
  
  
  
  
"startsAt": "string",
  
  
  
  
"endsAt": "string"
  
  
  
}
  
  
],
  
  
"discount": {
  
  
  
"endsAt": "string",
  
  
  
"amount": 0,
  
  
  
"percentage": 0,
  
  
  
"fullPrice": 0
  
  
}
  
}
]

Playground​

Authorization

Samples​


Get a contract by ID​

GET
/contracts/{contract_id}

Retrieves a specific contract by its unique identifier.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

contract_id*

The unique identifier of the contract

Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

The requested contract

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"name": "string",
  
"userId": "string",
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"confirmedAt": "string",
  
"updatedAt": "string",
  
"price": 0,
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"manageUrl": "string",
  
"contractDuration": "string",
  
"issuesRemaining": 0,
  
"items": [
  
  
{
  
  
  
"id": "string",
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"purchaseOptionName": "string",
  
  
  
"name": "string",
  
  
  
"cover": "string",
  
  
  
"productType": "string",
  
  
  
"purchaseType": "string",
  
  
  
"isMultiseat": true,
  
  
  
"quantity": 0,
  
  
  
"seats": 0
  
  
}
  
],
  
"status": "string",
  
"isActive": true,
  
"recurringInterval": "string",
  
"recurringTime": 0,
  
"recurringPrice": [
  
  
{
  
  
  
"from": "string",
  
  
  
"to": "string",
  
  
  
"id": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"interval": "string",
  
  
  
"intervalCount": 0,
  
  
  
"discount": {
  
  
  
  
"amount": 0,
  
  
  
  
"percentage": 0,
  
  
  
  
"fullPrice": 0,
  
  
  
  
"codes": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
"amount": 0
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
],
  
"willCancelAt": "string",
  
"cancelRequestedAt": "string",
  
"canceledAt": "string",
  
"cancelReason": "string",
  
"expiresAt": "string",
  
"origin": {
  
  
"type": "string",
  
  
"id": "string"
  
},
  
"paymentData": {
  
  
"method": "string",
  
  
"description": "string",
  
  
"brand": "string",
  
  
"walletType": "string"
  
},
  
"appliedDiscounts": [
  
  
{
  
  
  
"code": "string",
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"id": "string",
  
  
  
"status": "string",
  
  
  
"startsAt": "string",
  
  
  
"endsAt": "string"
  
  
}
  
],
  
"discount": {
  
  
"endsAt": "string",
  
  
"amount": 0,
  
  
"percentage": 0,
  
  
"fullPrice": 0
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


List upgrade options​

GET
/contracts/{contract_id}/upgrade-options

Lists the products and purchase options each item of the contract can be upgraded, downgraded, or switched to. An empty array means the contract cannot be changed.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

contract_id*

The unique identifier of the contract

Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

The available upgrade and downgrade paths for the contract

application/json
JSON
[
  
{
  
  
"itemId": "string",
  
  
"sku": "string",
  
  
"purchaseOptionId": "string",
  
  
"paths": [
  
  
  
{
  
  
  
  
"type": "string",
  
  
  
  
"sku": "string",
  
  
  
  
"purchaseOptionId": "string",
  
  
  
  
"title": "string",
  
  
  
  
"cover": "string",
  
  
  
  
"description": "string",
  
  
  
  
"features": [
  
  
  
  
  
"string"
  
  
  
  
]
  
  
  
}
  
  
]
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


Cancel a contract​

POST
/contracts/{contract_id}/cancel

Cancels a specific contract. For subscriptions, this typically means they will not renew at the end of the current billing period.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

contract_id*

The unique identifier of the contract

Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Request Body​

application/json
JSON
{
  
"reason": "string",
  
"comment": "string"
}

Responses​

Contract cancelled successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Reactivate a contract​

POST
/contracts/{contract_id}/reactivate

Removes a scheduled cancellation, so the contract renews again as before. Only a contract that is still running can be reactivated: one that has already ended has to be bought again. Reactivating a contract that is not set to cancel returns it unchanged.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

contract_id*

The unique identifier of the contract

Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

The contract, no longer set to cancel

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"name": "string",
  
"userId": "string",
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"confirmedAt": "string",
  
"updatedAt": "string",
  
"price": 0,
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"manageUrl": "string",
  
"contractDuration": "string",
  
"issuesRemaining": 0,
  
"items": [
  
  
{
  
  
  
"id": "string",
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"purchaseOptionName": "string",
  
  
  
"name": "string",
  
  
  
"cover": "string",
  
  
  
"productType": "string",
  
  
  
"purchaseType": "string",
  
  
  
"isMultiseat": true,
  
  
  
"quantity": 0,
  
  
  
"seats": 0
  
  
}
  
],
  
"status": "string",
  
"isActive": true,
  
"recurringInterval": "string",
  
"recurringTime": 0,
  
"recurringPrice": [
  
  
{
  
  
  
"from": "string",
  
  
  
"to": "string",
  
  
  
"id": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"interval": "string",
  
  
  
"intervalCount": 0,
  
  
  
"discount": {
  
  
  
  
"amount": 0,
  
  
  
  
"percentage": 0,
  
  
  
  
"fullPrice": 0,
  
  
  
  
"codes": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"name": "string",
  
  
  
  
  
  
"amount": 0
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
],
  
"willCancelAt": "string",
  
"cancelRequestedAt": "string",
  
"canceledAt": "string",
  
"cancelReason": "string",
  
"expiresAt": "string",
  
"origin": {
  
  
"type": "string",
  
  
"id": "string"
  
},
  
"paymentData": {
  
  
"method": "string",
  
  
"description": "string",
  
  
"brand": "string",
  
  
"walletType": "string"
  
},
  
"appliedDiscounts": [
  
  
{
  
  
  
"code": "string",
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"id": "string",
  
  
  
"status": "string",
  
  
  
"startsAt": "string",
  
  
  
"endsAt": "string"
  
  
}
  
],
  
"discount": {
  
  
"endsAt": "string",
  
  
"amount": 0,
  
  
"percentage": 0,
  
  
"fullPrice": 0
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​


Create an amendment​

POST
/contracts/{contract_id}/amendments

Prepares a change to a contract: DISCOUNT applies a discount code, PLAN_CHANGE moves the contract to another product or purchase option. The amendment is PENDING and changes nothing until it is confirmed with POST /contracts/{contract_id}/amendments/{amendment_id}/confirm, so it doubles as a preview: nextPrice and proration show what the change costs. A plan change must be one of the paths listed by GET /contracts/{contract_id}/upgrade-options, and only works on an active recurring contract that is not set to cancel.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

contract_id*

The unique identifier of the contract

Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Request Body​

application/json
JSON
{
  
"type": "string",
  
"discountCode": "string"
}

Responses​

The created amendment

application/json
JSON
{
  
"id": "string",
  
"contractId": "string",
  
"status": "string",
  
"appliedDiscounts": [
  
  
"string"
  
],
  
"amendmentType": "string",
  
"nextBill": {
  
  
"total": 0,
  
  
"currency": "string",
  
  
"date": "string"
  
},
  
"nextBillAt": "string",
  
"nextPrice": 0,
  
"currency": "string",
  
"items": [
  
  
{
  
  
  
"id": "item_1",
  
  
  
"sku": "sid:acme-plus-yearly",
  
  
  
"purchaseOptionId": "yearly"
  
  
}
  
],
  
"proration": {
  
  
"method": "string",
  
  
"amount": 41.5,
  
  
"currency": "SEK",
  
  
"appliesAt": "2026-12-01T00:00:00.000Z"
  
}
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Confirm an amendment​

POST
/contracts/{contract_id}/amendments/{amendment_id}/confirm

Confirms a pending amendment for a contract. For a plan change whose proration.method is UPFRONT or RESTART_PERIOD, proration.amount is charged to the saved payment method now; a declined payment answers 400. A plan change cannot be confirmed while the contract is set to cancel: reactivate it first.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

contract_id*

The unique identifier of the contract

Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"
amendment_id*

The unique identifier of the amendment

Type
string
Required
Example"amendment123"

Responses​

Amendment confirmed successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Variables
Key
Value

Samples​


bills​


List all bills​

GET
/bills

Retrieves all bills for the current user, excluding draft and expired bills. Results are sorted by creation date (newest first).

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

A list of the user's bills

application/json
JSON
[
  
{
  
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
  
"contractId": "a1b2c3d4e5f6g7h8i9j0",
  
  
"items": [
  
  
  
{
  
  
  
  
"sku": "string",
  
  
  
  
"title": "string",
  
  
  
  
"purchaseOptionId": "string"
  
  
  
}
  
  
],
  
  
"price": 0,
  
  
"currency": "string",
  
  
"receiptUrl": "string",
  
  
"paymentProvider": "string",
  
  
"paymentMethod": "string",
  
  
"status": "string",
  
  
"updatedAt": "string",
  
  
"createdAt": "string"
  
}
]

Playground​

Authorization

Samples​


Get a bill by ID​

GET
/bills/{id}

Retrieves a specific bill by its unique identifier.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

The unique identifier of the bill

Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

The requested bill

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"contractId": "a1b2c3d4e5f6g7h8i9j0",
  
"items": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"title": "string",
  
  
  
"purchaseOptionId": "string"
  
  
}
  
],
  
"price": 0,
  
"currency": "string",
  
"receiptUrl": "string",
  
"paymentProvider": "string",
  
"paymentMethod": "string",
  
"status": "string",
  
"updatedAt": "string",
  
"createdAt": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


List all entitlements​

GET
/entitlements

Retrieves all entitlements for the current user with optional filtering by type, SKU, or purchase option ID.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

type

Filter by entitlement type

Type
string
Valid values
"article""audiobook""ebook""bundle""podcast""pass""publication""physical_issue"
Example"article"
sku

Filter by SKU

Type
string
Example"premium-article-123"
purchase-option-id

Filter by purchase option ID

Type
string
Example"one-time"
wait-for-entitlement-after

Wait for entitlements created after this timestamp

Type
string
Example"2023-01-01T00:00:00Z"

Responses​

A list of the user's entitlements

application/json
JSON
[
  
{
  
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
  
"sku": "string",
  
  
"purchaseOption": "string",
  
  
"cover": "string",
  
  
"title": "string",
  
  
"url": "string",
  
  
"presentationUrl": "string",
  
  
"publisherContentId": "string",
  
  
"type": "string",
  
  
"origin": {
  
  
  
"type": "string",
  
  
  
"id": "string",
  
  
  
"listId": "string",
  
  
  
"name": "string"
  
  
},
  
  
"hasAccess": true,
  
  
"isPaused": true,
  
  
"createdAt": "string",
  
  
"updatedAt": "string",
  
  
"token": "string",
  
  
"expiresAt": "string"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


Get an entitlement by ID​

GET
/entitlements/{id}

Retrieves a specific entitlement by its unique identifier.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

The unique identifier of the entitlement

Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

The requested entitlement

application/json
JSON
{
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
"sku": "string",
  
"purchaseOption": "string",
  
"cover": "string",
  
"title": "string",
  
"url": "string",
  
"presentationUrl": "string",
  
"publisherContentId": "string",
  
"type": "string",
  
"origin": {
  
  
"type": "string",
  
  
"id": "string",
  
  
"listId": "string",
  
  
"name": "string"
  
},
  
"hasAccess": true,
  
"isPaused": true,
  
"createdAt": "string",
  
"updatedAt": "string",
  
"token": "string",
  
"expiresAt": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Get access information for an entitlement​

GET
/entitlements/{id}/access

Retrieves access information (URL and token) for a specific entitlement. The access type (URL or RSS) is determined based on the entitlement type.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

The unique identifier of the entitlement

Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

Access information for the entitlement

application/json
JSON
{
  
"id": "string",
  
"url": "string",
  
"token": "string",
  
"title": "string",
  
"filename": "string",
  
"type": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


transactions​


List transactions​

GET
/transactions

Retrieves all transactions for the current user, with optional filtering by search query.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

q

Search query to filter transactions

Type
string
Example"premium"

Responses​

A list of the user's transactions

application/json
JSON
[
  
{
  
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
  
"amount": 0,
  
  
"currency": "string",
  
  
"contractId": "string",
  
  
"isRefund": true,
  
  
"userId": "string",
  
  
"billId": "string",
  
  
"updatedAt": "string",
  
  
"createdAt": "string"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


subscriptions​


List subscriptions​

GET
/subscriptions

Retrieves all subscriptions for the current user. This includes both active and canceled subscriptions.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

A list of the user's subscriptions

application/json
JSON
[
  
{
  
  
"id": "string",
  
  
"currency": "string",
  
  
"cancelAt": "string",
  
  
"createdAt": "string",
  
  
"status": "string",
  
  
"product": {
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"image": "string",
  
  
  
"optionId": "string",
  
  
  
"sku": "string"
  
  
},
  
  
"totalIssues": 0,
  
  
"remainingIssues": 0,
  
  
"price": 0,
  
  
"nextPrice": 0,
  
  
"nextPaymentAt": "string",
  
  
"hasAccess": true,
  
  
"manageUrl": "string",
  
  
"userId": "string"
  
}
]

Playground​

Authorization

Samples​


Get a subscription by ID​

GET
/subscriptions/{id}

Retrieves a specific subscription by its unique identifier.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

The unique identifier of the subscription

Type
string
Required
Example"1d78271264b9c76d5842911dd70b4353"

Responses​

The requested subscription

application/json
JSON
{
  
"id": "string",
  
"currency": "string",
  
"cancelAt": "string",
  
"createdAt": "string",
  
"status": "string",
  
"product": {
  
  
"name": "string",
  
  
"description": "string",
  
  
"image": "string",
  
  
"optionId": "string",
  
  
"sku": "string"
  
},
  
"totalIssues": 0,
  
"remainingIssues": 0,
  
"price": 0,
  
"nextPrice": 0,
  
"nextPaymentAt": "string",
  
"hasAccess": true,
  
"manageUrl": "string",
  
"userId": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Get all user metadata​

GET
/user-metadata

Retrieves all metadata entries for the current user.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

Object with metadata key-value pairs

application/json
JSON
{
  
"additionalProperties": "string"
}

Playground​

Authorization

Samples​


Set user metadata value​

PUT
/user-metadata/{id}

Sets a metadata value for the current user with the specified key.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

The key of the metadata entry

Type
string
Required
Example"preferences"

Request Body​

text/plain
JSON
"string"

Responses​

Metadata value set successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Delete user metadata value​

DELETE
/user-metadata/{id}

Deletes a metadata value for the current user with the specified key.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

The key of the metadata entry

Type
string
Required
Example"preferences"

Responses​

Metadata value deleted successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization
Variables
Key
Value

Samples​


List all tallies​

GET
/tallies

Retrieve all tallies for the authenticated user.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

A record of tallies where keys are tally IDs and values are the tally values

application/json
JSON
{
  
"additionalProperties": [
  
  
"string"
  
]
}

Playground​

Authorization

Samples​


Get a tally by ID​

GET
/tallies/{id}

Retrieve a specific tally by its ID for the authenticated user.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"test"

Responses​

The tally value for the specified ID

application/json
JSON
[
  
"string"
]

Playground​

Authorization
Variables
Key
Value

Samples​


Update a tally​

PUT
/tallies/{id}

Set a tally to a new value for the authenticated user.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"test"

Request Body​

application/json
JSON
{
  
"value": "string",
  
"policies": {
  
  
"ttl": 0,
  
  
"maxItems": 0,
  
  
"unique": true,
  
  
"overflow": "string",
  
  
"ipSessionSharing": true
  
}
}

Responses​

The updated tally object

application/json
JSON
{
  
"id": "string",
  
"value": [
  
  
"string"
  
],
  
"policies": {
  
  
"ttl": 0,
  
  
"maxItems": 0,
  
  
"unique": true,
  
  
"overflow": "string",
  
  
"ipSessionSharing": true
  
},
  
"createdAt": "string",
  
"updatedAt": "string",
  
"expiresAt": "string"
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Push value to tally​

POST
/tallies/{id}/push

Add a new value to an existing tally list for the authenticated user.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*
Type
string
Required
Example"test"

Request Body​

application/json
JSON
{
  
"value": "string",
  
"policies": {
  
  
"ttl": 0,
  
  
"maxItems": 0,
  
  
"unique": true,
  
  
"overflow": "string",
  
  
"ipSessionSharing": true
  
}
}

Responses​

The updated tally value after pushing the new value

application/json
JSON
[
  
"string"
]

Playground​

Authorization
Variables
Key
Value
Body

Samples​


List fulfillments​

GET
/fulfillments

Retrieves all fulfillments for a specific SKU. Useful for tracking delivery status of physical items.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

sku*

The SKU of the publication which can be found by querying the entitlements of type bundle

Type
string
Required
Example"magazine-april-2023"

Responses​

A list of user's fulfillments for the requested SKU

application/json
JSON
[
  
{
  
  
"status": "string",
  
  
"updatedAt": "string",
  
  
"createdAt": "string",
  
  
"deliversAt": "string",
  
  
"sku": "string",
  
  
"title": "string",
  
  
"id": "string",
  
  
"cover": "string",
  
  
"numericId": 0,
  
  
"deliveryProvider": "string",
  
  
"itemId": "string",
  
  
"copies": 0
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


Request delivery for a fulfillment item​

POST
/fulfillments/{id}/request-delivery

Request a new delivery for a specific fulfillment item by ID and SKU.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

The fulfillment item ID

Type
string
Required
Example"item123"

Request Body​

application/json
JSON
{
  
"sku": "magazine-april-2023"
}

Responses​

Delivery request result

application/json
JSON
{
  
"ok": true
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


tags​


List user tags​

GET
/tags

Retrieve all tags associated with the authenticated user.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

Array of user tags

application/json
JSON
[
  
"string"
]

Playground​

Authorization

Samples​


Add a tag​

POST
/tags

Add a new tag to the authenticated user.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

text/plain
JSON
"premium"

Responses​

Confirmation that the tag was added

application/json
JSON
"string"

Playground​

Authorization
Body

Samples​


Delete a tag​

DELETE
/tags/{tag}

Remove a tag from the authenticated user.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

tag*

Tag value to delete

Type
string
Required
Example"premium"

Responses​

Confirmation that the tag was deleted

application/json
JSON
"string"

Playground​

Authorization
Variables
Key
Value

Samples​


Get user profile​

GET
/profile

Retrieves the authenticated user's profile information.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

The user's profile information

application/json
JSON
{
  
"userId": "string",
  
"firstName": "string",
  
"lastName": "string",
  
"email": "string",
  
"emailVerified": true,
  
"locale": "string",
  
"nickname": "string",
  
"picture": "string",
  
"name": "string",
  
"mobilePhone": "string",
  
"workPhone": "string",
  
"homePhone": "string",
  
"tags": [
  
  
"string"
  
],
  
"user_metadata": {
  
  
"additionalProperties": "string"
  
},
  
"billingAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"deliveryAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"createdAt": "string",
  
"updatedAt": "string",
  
"companyInfo": {
  
  
"companyName": "string",
  
  
"vatNr": "string",
  
  
"invoiceEmail": "string"
  
},
  
"company": "string",
  
"sub": "string",
  
"given_name": "string",
  
"family_name": "string",
  
"phone_number": "string"
}

Playground​

Authorization

Samples​


Delete own profile​

DELETE
/profile

Allows the authenticated user to delete their own account. This action is irreversible.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

Profile deleted successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization

Samples​


Update user profile​

PATCH
/profile

Updates the authenticated user's profile information with the provided data.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"firstName": "John",
  
"lastName": "Doe",
  
"nickname": "Johnny",
  
"mobilePhone": "+1234567890",
  
"workPhone": "+1234567891",
  
"homePhone": "+1234567892",
  
"billingAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "Stockholm",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"deliveryAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "Stockholm",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"user_metadata": {
  
  
"additionalProperties": "string"
  
},
  
"companyInfo": {
  
  
"companyName": "string",
  
  
"vatNr": "string",
  
  
"invoiceEmail": "string"
  
},
  
"given_name": "string",
  
"family_name": "string",
  
"phone_number": "string"
}

Responses​

The updated user profile

application/json
JSON
{
  
"userId": "string",
  
"firstName": "string",
  
"lastName": "string",
  
"email": "string",
  
"emailVerified": true,
  
"locale": "string",
  
"nickname": "string",
  
"picture": "string",
  
"name": "string",
  
"mobilePhone": "string",
  
"workPhone": "string",
  
"homePhone": "string",
  
"tags": [
  
  
"string"
  
],
  
"user_metadata": {
  
  
"additionalProperties": "string"
  
},
  
"billingAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"deliveryAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"createdAt": "string",
  
"updatedAt": "string",
  
"companyInfo": {
  
  
"companyName": "string",
  
  
"vatNr": "string",
  
  
"invoiceEmail": "string"
  
},
  
"company": "string",
  
"sub": "string",
  
"given_name": "string",
  
"family_name": "string",
  
"phone_number": "string"
}

Playground​

Authorization
Body

Samples​


Check Spotify link status​

GET
/profile/spotify-link

Checks if the user has connected their Spotify account.

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Spotify link status

application/json
JSON
{
  
"isSpotifyLinked": true
}
Authorization

Unlink Spotify account​

POST
/profile/unlink-spotify

Unlinks the user's connected Spotify account from their profile.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

Spotify account unlinked successfully

application/json
JSON
{
  
"success": true
}

Playground​

Authorization

Samples​


Get a product by SKU​

GET
/products/{sku}

Retrieves a specific product by its unique SKU identifier.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

sku*

The unique stock keeping unit (SKU) identifier of the product

Type
string
Required
Example"sid:PRVc_h8FIgR2ntoZh9SNu"

Responses​

The requested product

application/json
JSON
{
  
"cover": "string",
  
"language": "string",
  
"createdAt": "string",
  
"updatedAt": "string",
  
"sku": "string",
  
"title": "string",
  
"productType": "string",
  
"publisherContentId": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Auto-onboard a product​

POST
/products/{sku}/auto-onboard

Triggers the auto-onboarding process for a product. This typically grants additional entitlements based on external systems when supported by the product.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

sku*

The unique stock keeping unit (SKU) identifier of the product

Type
string
Required
Example"sid:PRVc_h8FIgR2ntoZh9SNu"

Responses​

The entitlements returned from the auto-onboard process

application/json
JSON
[
  
{
  
  
"id": "1d78271264b9c76d5842911dd70b4353",
  
  
"sku": "string",
  
  
"purchaseOption": "string",
  
  
"cover": "string",
  
  
"title": "string",
  
  
"url": "string",
  
  
"presentationUrl": "string",
  
  
"publisherContentId": "string",
  
  
"type": "string",
  
  
"origin": {
  
  
  
"type": "string",
  
  
  
"id": "string",
  
  
  
"listId": "string",
  
  
  
"name": "string"
  
  
},
  
  
"hasAccess": true,
  
  
"isPaused": true,
  
  
"createdAt": "string",
  
  
"updatedAt": "string",
  
  
"token": "string",
  
  
"expiresAt": "string"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


payment-issues​


List payment issues​

GET
/payment-issues

Retrieves all payment issues for the current user. This includes overdue payments and expired payment methods.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

A list of the user's payment issues

application/json
JSON
[
  
{
  
  
"contractId": "1d78271264b9c76d5842911dd70b4353",
  
  
"createdAt": "string",
  
  
"updatedAt": "string",
  
  
"nextPaymentAt": "string",
  
  
"manageUrl": "string",
  
  
"status": "string"
  
}
]

Playground​

Authorization

Samples​


Create a checkout​

POST
/checkouts

Creates a new checkout session with the specified items and settings.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"url": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"geoRestrictions": {
  
  
  
  
"countries": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"type": "string"
  
  
  
}
  
  
}
  
],
  
"address": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"businessAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"email": "string",
  
"givenName": "string",
  
"familyName": "string",
  
"birthDate": "string",
  
"phoneNumber": "string",
  
"country": "string",
  
"referralEmail": "string",
  
"language": "string",
  
"redirectUrl": "string",
  
"isBusiness": true,
  
"price": 0,
  
"currency": "string",
  
"anonymousUserId": "string",
  
"attribution": {
  
  
"utmSource": "string",
  
  
"utmMedium": "string",
  
  
"utmCampaign": "string",
  
  
"utmTerm": "string",
  
  
"utmContent": "string",
  
  
"source": "string",
  
  
"sourceId": "string",
  
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
  
"strategyId": "st_abc123",
  
  
"itemSrc": "string",
  
  
"referrer": "string",
  
  
"publisherContentId": "string",
  
  
"_ga": "string",
  
  
"_gid": "string",
  
  
"_fbp": "string",
  
  
"_fbc": "string",
  
  
"_pk_id": "string",
  
  
"gaSessionId": "string"
  
},
  
"paymentData": {
  
  
"provider": "string",
  
  
"method": "string"
  
},
  
"paymentMethodsFilter": [
  
  
{
  
  
  
"provider": "string",
  
  
  
"methods": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"fieldSettings": {
  
  
"name": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"phone": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"birthdate": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"referral": {
  
  
  
"enabled": true
  
  
}
  
},
  
"giftMode": true,
  
"requireAddress": true,
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"requestedDiscountCodes": [
  
  
"string"
  
],
  
"payerEmail": "string",
  
"redirectLabel": "Start reading ACME Plus"
}

Responses​

The created checkout session

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"url": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"geoRestrictions": {
  
  
  
  
"countries": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"type": "string"
  
  
  
}
  
  
}
  
],
  
"address": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"businessAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"email": "string",
  
"givenName": "string",
  
"familyName": "string",
  
"birthDate": "string",
  
"phoneNumber": "string",
  
"country": "string",
  
"referralEmail": "string",
  
"language": "string",
  
"redirectUrl": "string",
  
"isBusiness": true,
  
"price": 0,
  
"currency": "string",
  
"anonymousUserId": "string",
  
"attribution": {
  
  
"utmSource": "string",
  
  
"utmMedium": "string",
  
  
"utmCampaign": "string",
  
  
"utmTerm": "string",
  
  
"utmContent": "string",
  
  
"source": "string",
  
  
"sourceId": "string",
  
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
  
"strategyId": "st_abc123",
  
  
"itemSrc": "string",
  
  
"referrer": "string",
  
  
"publisherContentId": "string",
  
  
"_ga": "string",
  
  
"_gid": "string",
  
  
"_fbp": "string",
  
  
"_fbc": "string",
  
  
"_pk_id": "string",
  
  
"gaSessionId": "string"
  
},
  
"paymentData": {
  
  
"provider": "string",
  
  
"method": "string"
  
},
  
"paymentMethodsFilter": [
  
  
{
  
  
  
"provider": "string",
  
  
  
"methods": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"fieldSettings": {
  
  
"name": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"phone": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"birthdate": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"referral": {
  
  
  
"enabled": true
  
  
}
  
},
  
"giftMode": true,
  
"requireAddress": true,
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"id": "string",
  
"checkoutUrl": "string",
  
"status": "string",
  
"type": "string",
  
"itemsOwned": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"title": "string"
  
  
}
  
],
  
"appliedDiscountCodes": [
  
  
{
  
  
  
"name": "string",
  
  
  
"id": "string",
  
  
  
"code": "string",
  
  
  
"description": "string",
  
  
  
"status": "string"
  
  
}
  
],
  
"availablePaymentMethods": [
  
  
{
  
  
  
"provider": "string",
  
  
  
"methods": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground​

Authorization
Body

Samples​


Get a checkout by ID​

GET
/checkouts/{id}

Retrieves a specific checkout session by its ID.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

The unique identifier of the checkout

Type
string
Required
Example"checkout123"

Responses​

The requested checkout session

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"url": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"geoRestrictions": {
  
  
  
  
"countries": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"type": "string"
  
  
  
}
  
  
}
  
],
  
"address": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"businessAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"email": "string",
  
"givenName": "string",
  
"familyName": "string",
  
"birthDate": "string",
  
"phoneNumber": "string",
  
"country": "string",
  
"referralEmail": "string",
  
"language": "string",
  
"redirectUrl": "string",
  
"isBusiness": true,
  
"price": 0,
  
"currency": "string",
  
"anonymousUserId": "string",
  
"attribution": {
  
  
"utmSource": "string",
  
  
"utmMedium": "string",
  
  
"utmCampaign": "string",
  
  
"utmTerm": "string",
  
  
"utmContent": "string",
  
  
"source": "string",
  
  
"sourceId": "string",
  
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
  
"strategyId": "st_abc123",
  
  
"itemSrc": "string",
  
  
"referrer": "string",
  
  
"publisherContentId": "string",
  
  
"_ga": "string",
  
  
"_gid": "string",
  
  
"_fbp": "string",
  
  
"_fbc": "string",
  
  
"_pk_id": "string",
  
  
"gaSessionId": "string"
  
},
  
"paymentData": {
  
  
"provider": "string",
  
  
"method": "string"
  
},
  
"paymentMethodsFilter": [
  
  
{
  
  
  
"provider": "string",
  
  
  
"methods": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"fieldSettings": {
  
  
"name": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"phone": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"birthdate": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"referral": {
  
  
  
"enabled": true
  
  
}
  
},
  
"giftMode": true,
  
"requireAddress": true,
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"id": "string",
  
"checkoutUrl": "string",
  
"status": "string",
  
"type": "string",
  
"itemsOwned": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"title": "string"
  
  
}
  
],
  
"appliedDiscountCodes": [
  
  
{
  
  
  
"name": "string",
  
  
  
"id": "string",
  
  
  
"code": "string",
  
  
  
"description": "string",
  
  
  
"status": "string"
  
  
}
  
],
  
"availablePaymentMethods": [
  
  
{
  
  
  
"provider": "string",
  
  
  
"methods": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Update a checkout​

PATCH
/checkouts/{id}

Updates an existing checkout session with new customer information or payment method.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

id*

The unique identifier of the checkout

Type
string
Required
Example"checkout123"

Request Body​

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"url": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"geoRestrictions": {
  
  
  
  
"countries": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"type": "string"
  
  
  
}
  
  
}
  
],
  
"address": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"businessAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"email": "string",
  
"givenName": "string",
  
"familyName": "string",
  
"birthDate": "string",
  
"phoneNumber": "string",
  
"country": "string",
  
"referralEmail": "string",
  
"language": "string",
  
"redirectUrl": "string",
  
"isBusiness": true,
  
"price": 0,
  
"currency": "string",
  
"anonymousUserId": "string",
  
"attribution": {
  
  
"utmSource": "string",
  
  
"utmMedium": "string",
  
  
"utmCampaign": "string",
  
  
"utmTerm": "string",
  
  
"utmContent": "string",
  
  
"source": "string",
  
  
"sourceId": "string",
  
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
  
"strategyId": "st_abc123",
  
  
"itemSrc": "string",
  
  
"referrer": "string",
  
  
"publisherContentId": "string",
  
  
"_ga": "string",
  
  
"_gid": "string",
  
  
"_fbp": "string",
  
  
"_fbc": "string",
  
  
"_pk_id": "string",
  
  
"gaSessionId": "string"
  
},
  
"paymentData": {
  
  
"provider": "string",
  
  
"method": "string"
  
},
  
"paymentMethodsFilter": [
  
  
{
  
  
  
"provider": "string",
  
  
  
"methods": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"fieldSettings": {
  
  
"name": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"phone": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"birthdate": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"referral": {
  
  
  
"enabled": true
  
  
}
  
},
  
"giftMode": true,
  
"requireAddress": true,
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"requestedDiscountCodes": [
  
  
"string"
  
],
  
"payerEmail": "string"
}

Responses​

The updated checkout session

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"url": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"price": 0,
  
  
  
"currency": "string",
  
  
  
"geoRestrictions": {
  
  
  
  
"countries": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"type": "string"
  
  
  
}
  
  
}
  
],
  
"address": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"businessAddress": {
  
  
"country": "string",
  
  
"zip": "string",
  
  
"city": "string",
  
  
"street": "string",
  
  
"co": "string",
  
  
"lastName": "string",
  
  
"firstName": "string"
  
},
  
"email": "string",
  
"givenName": "string",
  
"familyName": "string",
  
"birthDate": "string",
  
"phoneNumber": "string",
  
"country": "string",
  
"referralEmail": "string",
  
"language": "string",
  
"redirectUrl": "string",
  
"isBusiness": true,
  
"price": 0,
  
"currency": "string",
  
"anonymousUserId": "string",
  
"attribution": {
  
  
"utmSource": "string",
  
  
"utmMedium": "string",
  
  
"utmCampaign": "string",
  
  
"utmTerm": "string",
  
  
"utmContent": "string",
  
  
"source": "string",
  
  
"sourceId": "string",
  
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
  
"strategyId": "st_abc123",
  
  
"itemSrc": "string",
  
  
"referrer": "string",
  
  
"publisherContentId": "string",
  
  
"_ga": "string",
  
  
"_gid": "string",
  
  
"_fbp": "string",
  
  
"_fbc": "string",
  
  
"_pk_id": "string",
  
  
"gaSessionId": "string"
  
},
  
"paymentData": {
  
  
"provider": "string",
  
  
"method": "string"
  
},
  
"paymentMethodsFilter": [
  
  
{
  
  
  
"provider": "string",
  
  
  
"methods": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"fieldSettings": {
  
  
"name": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"phone": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"birthdate": {
  
  
  
"enabled": true,
  
  
  
"required": true
  
  
},
  
  
"referral": {
  
  
  
"enabled": true
  
  
}
  
},
  
"giftMode": true,
  
"requireAddress": true,
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"id": "string",
  
"checkoutUrl": "string",
  
"status": "string",
  
"type": "string",
  
"itemsOwned": [
  
  
{
  
  
  
"sku": "string",
  
  
  
"purchaseOptionId": "string",
  
  
  
"title": "string"
  
  
}
  
],
  
"appliedDiscountCodes": [
  
  
{
  
  
  
"name": "string",
  
  
  
"id": "string",
  
  
  
"code": "string",
  
  
  
"description": "string",
  
  
  
"status": "string"
  
  
}
  
],
  
"availablePaymentMethods": [
  
  
{
  
  
  
"provider": "string",
  
  
  
"methods": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"payer": {
  
  
"id": "string",
  
  
"email": "string"
  
},
  
"createdAt": "string",
  
"updatedAt": "string"
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


vendor​


Get vendor settings​

GET
/vendor

Retrieves the current vendor settings and configuration.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

The vendor settings and configuration

application/json
JSON
{
  
"id": "vendor123",
  
"name": "Sesamy Publisher",
  
"logo": "https://example.com/logo.png",
  
"additionalProperties": "string"
}

Playground​

Authorization

Samples​


List the vendors where the user has an account​

GET
/vendors

Get the vendors that have a user account matching the authenticated user's email address.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

The vendors with a user account matching the user's email

application/json
JSON
[
  
{
  
  
"name": "ACME",
  
  
"id": "acme",
  
  
"logo": "https://example.com/logo.png"
  
}
]

Playground​

Authorization

Samples​


Get paywall by ID​

GET
/paywalls/{paywallId}

Retrieves the rendered paywall configuration and settings for the specified paywall ID. This is the public render shape: it does not carry the admin-only name, status, entity, createdAt, modifiedAt or previewUrl fields. A strategy id (st_…) executes the strategy for the visitor and returns the paywall it selected, plus decisionId and strategyId; the query parameters only apply to strategy ids.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

paywallId*

Unique identifier of the paywall

Type
string
Required
Example"pw123456"

Query Parameters

referrer

Strategy ids only: full referrer URL the visitor arrived from (document.referrer), parsed server-side into provider/medium

Type
string
Example"https://www.google.com/"
utm_source

Strategy ids only: UTM source

Type
string
utm_medium

Strategy ids only: UTM medium

Type
string
utm_campaign

Strategy ids only: UTM campaign

Type
string
utm_term

Strategy ids only: UTM term

Type
string
utm_content

Strategy ids only: UTM content

Type
string
contentId

Strategy ids only: publisher content id of the article the paywall is shown on

Type
string
Example"article-2024-01-15-news"

Responses​

The paywall information and configuration

application/json
JSON
{
  
"id": "aM8o7LqpkGZJ-szyPwe_E",
  
"vendorId": "acme",
  
"currency": "SEK",
  
"version": 2,
  
"settings": {
  
  
"template": "BOXES",
  
  
"useDefaultLogo": true,
  
  
"useDefaultCurrency": true,
  
  
"useDefaultColor": true,
  
  
"styling": {
  
  
  
"dropShadow": true,
  
  
  
"backgroundColor": "#000000",
  
  
  
"showBackground": false
  
  
},
  
  
"displayOptions": {
  
  
  
"enableGift": true,
  
  
  
"enableCompany": true,
  
  
  
"enableLoginButton": true
  
  
},
  
  
"loginFields": {
  
  
  
"name": true
  
  
},
  
  
"leaky": {
  
  
  
"enabled": true,
  
  
  
"count": 3,
  
  
  
"periodInHours": 720
  
  
},
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
"redirectLabel": "Go to ACME",
  
  
"showPricesExVat": false
  
},
  
"showLoginButton": true,
  
"subscriptions": [
  
  
{
  
  
  
"id": "R4gX0YSbSU1WJA7bCrbQw",
  
  
  
"sku": "sid:acme-plus-monthly",
  
  
  
"poId": "VDuH_poxqIPKW638Ok43q",
  
  
  
"title": "ACME Plus monthly",
  
  
  
"description": "<p>Only 720 kr/year - save 20%</p>",
  
  
  
"price": 99,
  
  
  
"discountPrice": 75,
  
  
  
"discountCode": "WELCOME20",
  
  
  
"periodText": "3 months",
  
  
  
"comparePeriodText": "month",
  
  
  
"tag": "Most popular",
  
  
  
"selected": true,
  
  
  
"features": [
  
  
  
  
[
  
  
  
  
  
"Daily news",
  
  
  
  
  
"Exclusive interviews"
  
  
  
  
]
  
  
  
],
  
  
  
"buttonText": "BUY ACCESS",
  
  
  
"readMoreLink": "https://acme.example.com/subscriptions",
  
  
  
"readMoreText": "Read more",
  
  
  
"preferBusiness": false,
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
"redirectLabel": "Start reading ACME Plus",
  
  
  
"discountId": "disc_acme_welcome",
  
  
  
"priceMode": "AUTOMATIC",
  
  
  
"url": "https://acme.example.com/business",
  
  
  
"pricePeriod": {
  
  
  
  
"period": "month",
  
  
  
  
"time": 3
  
  
  
},
  
  
  
"discountPeriod": {
  
  
  
  
"period": "month",
  
  
  
  
"time": 3
  
  
  
},
  
  
  
"discountMonths": 6,
  
  
  
"trialDays": 14
  
  
}
  
],
  
"subscriptionsUrl": "https://acme.example.com/subscriptions.json",
  
"features": [
  
  
[
  
  
  
"Everything on acme.example.com"
  
  
]
  
],
  
"mainColor": "#3377fe",
  
"headline": "Get access to ACME Plus",
  
"description": "<p>Read every article, on every device.</p>",
  
"logoUrl": "https://assets.sesamy.com/vendor-assets/acme/logo.svg",
  
"footerPaymentMethods": [
  
  
[
  
  
  
"visa",
  
  
  
"mastercard",
  
  
  
"google-pay",
  
  
  
"apple-pay"
  
  
]
  
],
  
"singlePurchase": {
  
  
"enabled": true,
  
  
"title": "Buy Now",
  
  
"description": "One-time purchase",
  
  
"discountCode": "WELCOME20",
  
  
"discountId": "disc_acme_welcome"
  
},
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
"strategyId": "st_abc123"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Deprecated

Execute a paywall strategy​

POST
/paywalls/strategies/{strategyId}/execute

Evaluates a paywall strategy by id against the visitor's context and returns the resolved paywall plus which rule matched. The body carries UTM attribution and optional content metadata; device, geo, referral, user and daily/weekly article read counts are supplied server-side. Evaluation never consumes a read. Anonymous — paywalls are evaluated for logged-out visitors.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

strategyId*

Unique identifier of the strategy

Type
string
Required
Example"str_abc123"

Query Parameters

debug

When "true", include debug info (requester object, cache, timing) in the response

Type
string
Valid values
"true""false"
Example"true"

Request Body​

application/json
JSON
{
  
"attribution": {
  
  
"source": "google",
  
  
"medium": "cpc",
  
  
"campaign": "summer_sale",
  
  
"term": "running shoes",
  
  
"content": "logolink",
  
  
"referrer": "https://www.google.com/"
  
},
  
"content": {
  
  
"contentId": "string",
  
  
"title": "string",
  
  
"type": "string",
  
  
"price": 0,
  
  
"currency": "string",
  
  
"publisherId": "string",
  
  
"contentType": "NewsArticle",
  
  
"section": "sports",
  
  
"tags": [
  
  
  
[
  
  
  
  
"football",
  
  
  
  
"premier-league"
  
  
  
]
  
  
],
  
  
"authors": [
  
  
  
[
  
  
  
  
"Jane Doe"
  
  
  
]
  
  
],
  
  
"publishedAt": "2026-01-15T09:00:00.000Z"
  
},
  
"debugUserAgent": "string"
}

Responses​

The resolved paywall and strategy match metadata

application/json
JSON
{
  
"paywallId": "pw123456",
  
"matchedNode": {
  
  
"id": "string",
  
  
"type": "string",
  
  
"label": "string"
  
},
  
"paywall": {
  
  
"id": "aM8o7LqpkGZJ-szyPwe_E",
  
  
"vendorId": "acme",
  
  
"currency": "SEK",
  
  
"version": 2,
  
  
"settings": {
  
  
  
"template": "BOXES",
  
  
  
"useDefaultLogo": true,
  
  
  
"useDefaultCurrency": true,
  
  
  
"useDefaultColor": true,
  
  
  
"styling": {
  
  
  
  
"dropShadow": true,
  
  
  
  
"backgroundColor": "#000000",
  
  
  
  
"showBackground": false
  
  
  
},
  
  
  
"displayOptions": {
  
  
  
  
"enableGift": true,
  
  
  
  
"enableCompany": true,
  
  
  
  
"enableLoginButton": true
  
  
  
},
  
  
  
"loginFields": {
  
  
  
  
"name": true
  
  
  
},
  
  
  
"leaky": {
  
  
  
  
"enabled": true,
  
  
  
  
"count": 3,
  
  
  
  
"periodInHours": 720
  
  
  
},
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
"redirectLabel": "Go to ACME",
  
  
  
"showPricesExVat": false
  
  
},
  
  
"showLoginButton": true,
  
  
"subscriptions": [
  
  
  
{
  
  
  
  
"id": "R4gX0YSbSU1WJA7bCrbQw",
  
  
  
  
"sku": "sid:acme-plus-monthly",
  
  
  
  
"poId": "VDuH_poxqIPKW638Ok43q",
  
  
  
  
"title": "ACME Plus monthly",
  
  
  
  
"description": "<p>Only 720 kr/year - save 20%</p>",
  
  
  
  
"price": 99,
  
  
  
  
"discountPrice": 75,
  
  
  
  
"discountCode": "WELCOME20",
  
  
  
  
"periodText": "3 months",
  
  
  
  
"comparePeriodText": "month",
  
  
  
  
"tag": "Most popular",
  
  
  
  
"selected": true,
  
  
  
  
"features": [
  
  
  
  
  
[
  
  
  
  
  
  
"Daily news",
  
  
  
  
  
  
"Exclusive interviews"
  
  
  
  
  
]
  
  
  
  
],
  
  
  
  
"buttonText": "BUY ACCESS",
  
  
  
  
"readMoreLink": "https://acme.example.com/subscriptions",
  
  
  
  
"readMoreText": "Read more",
  
  
  
  
"preferBusiness": false,
  
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
  
"redirectLabel": "Start reading ACME Plus",
  
  
  
  
"discountId": "disc_acme_welcome",
  
  
  
  
"priceMode": "AUTOMATIC",
  
  
  
  
"url": "https://acme.example.com/business",
  
  
  
  
"pricePeriod": {
  
  
  
  
  
"period": "month",
  
  
  
  
  
"time": 3
  
  
  
  
},
  
  
  
  
"discountPeriod": {
  
  
  
  
  
"period": "month",
  
  
  
  
  
"time": 3
  
  
  
  
},
  
  
  
  
"discountMonths": 6,
  
  
  
  
"trialDays": 14
  
  
  
}
  
  
],
  
  
"subscriptionsUrl": "https://acme.example.com/subscriptions.json",
  
  
"features": [
  
  
  
[
  
  
  
  
"Everything on acme.example.com"
  
  
  
]
  
  
],
  
  
"mainColor": "#3377fe",
  
  
"headline": "Get access to ACME Plus",
  
  
"description": "<p>Read every article, on every device.</p>",
  
  
"logoUrl": "https://assets.sesamy.com/vendor-assets/acme/logo.svg",
  
  
"footerPaymentMethods": [
  
  
  
[
  
  
  
  
"visa",
  
  
  
  
"mastercard",
  
  
  
  
"google-pay",
  
  
  
  
"apple-pay"
  
  
  
]
  
  
],
  
  
"singlePurchase": {
  
  
  
"enabled": true,
  
  
  
"title": "Buy Now",
  
  
  
"description": "One-time purchase",
  
  
  
"discountCode": "WELCOME20",
  
  
  
"discountId": "disc_acme_welcome"
  
  
},
  
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
  
"strategyId": "st_abc123"
  
},
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
"strategyId": "st_abc123",
  
"debug": {
  
  
"requesterObject": {
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"flow": {
  
  
  
"id": "string",
  
  
  
"name": "string",
  
  
  
"target": "string",
  
  
  
"fingerprint": "string"
  
  
},
  
  
"cache": {
  
  
  
"flowHit": true,
  
  
  
"paywallHit": true
  
  
},
  
  
"timing": {
  
  
  
"totalMs": 0,
  
  
  
"flowFetchAndEvaluationMs": 0,
  
  
  
"paywallFetchMs": 0
  
  
},
  
  
"trace": {
  
  
  
"path": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"edgesTaken": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"usedFallback": true,
  
  
  
"fallbackReason": "string"
  
  
}
  
}
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Deprecated

Register a strategy read for locally encoded content​

POST
/paywalls/strategies/{strategyId}/read

Evaluates the strategy and permits signed-in LOGIN or configured leaky access. Records successful reads without returning a signed link or decryption key; this cannot authorize protected content delivery. Checks and denied reads do not count.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

strategyId*
Type
string
Required

Request Body​

application/json
JSON
{
  
"attribution": {
  
  
"source": "google",
  
  
"medium": "cpc",
  
  
"campaign": "summer_sale",
  
  
"term": "running shoes",
  
  
"content": "logolink",
  
  
"referrer": "https://www.google.com/"
  
},
  
"content": {
  
  
"contentId": "string",
  
  
"title": "string",
  
  
"type": "string",
  
  
"price": 0,
  
  
"currency": "string",
  
  
"publisherId": "string",
  
  
"contentType": "NewsArticle",
  
  
"section": "sports",
  
  
"tags": [
  
  
  
[
  
  
  
  
"football",
  
  
  
  
"premier-league"
  
  
  
]
  
  
],
  
  
"authors": [
  
  
  
[
  
  
  
  
"Jane Doe"
  
  
  
]
  
  
],
  
  
"publishedAt": "2026-01-15T09:00:00.000Z"
  
},
  
"publisherContentId": "article-2024-01-15-news",
  
"url": "https://example.com/articles/my-article"
}

Responses​

Encoded read decision, without an access token

application/json
JSON
{
  
"status": "string",
  
"paywallId": "string",
  
"paywall": {
  
  
"id": "aM8o7LqpkGZJ-szyPwe_E",
  
  
"vendorId": "acme",
  
  
"currency": "SEK",
  
  
"version": 2,
  
  
"settings": {
  
  
  
"template": "BOXES",
  
  
  
"useDefaultLogo": true,
  
  
  
"useDefaultCurrency": true,
  
  
  
"useDefaultColor": true,
  
  
  
"styling": {
  
  
  
  
"dropShadow": true,
  
  
  
  
"backgroundColor": "#000000",
  
  
  
  
"showBackground": false
  
  
  
},
  
  
  
"displayOptions": {
  
  
  
  
"enableGift": true,
  
  
  
  
"enableCompany": true,
  
  
  
  
"enableLoginButton": true
  
  
  
},
  
  
  
"loginFields": {
  
  
  
  
"name": true
  
  
  
},
  
  
  
"leaky": {
  
  
  
  
"enabled": true,
  
  
  
  
"count": 3,
  
  
  
  
"periodInHours": 720
  
  
  
},
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
"redirectLabel": "Go to ACME",
  
  
  
"showPricesExVat": false
  
  
},
  
  
"showLoginButton": true,
  
  
"subscriptions": [
  
  
  
{
  
  
  
  
"id": "R4gX0YSbSU1WJA7bCrbQw",
  
  
  
  
"sku": "sid:acme-plus-monthly",
  
  
  
  
"poId": "VDuH_poxqIPKW638Ok43q",
  
  
  
  
"title": "ACME Plus monthly",
  
  
  
  
"description": "<p>Only 720 kr/year - save 20%</p>",
  
  
  
  
"price": 99,
  
  
  
  
"discountPrice": 75,
  
  
  
  
"discountCode": "WELCOME20",
  
  
  
  
"periodText": "3 months",
  
  
  
  
"comparePeriodText": "month",
  
  
  
  
"tag": "Most popular",
  
  
  
  
"selected": true,
  
  
  
  
"features": [
  
  
  
  
  
[
  
  
  
  
  
  
"Daily news",
  
  
  
  
  
  
"Exclusive interviews"
  
  
  
  
  
]
  
  
  
  
],
  
  
  
  
"buttonText": "BUY ACCESS",
  
  
  
  
"readMoreLink": "https://acme.example.com/subscriptions",
  
  
  
  
"readMoreText": "Read more",
  
  
  
  
"preferBusiness": false,
  
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
  
"redirectLabel": "Start reading ACME Plus",
  
  
  
  
"discountId": "disc_acme_welcome",
  
  
  
  
"priceMode": "AUTOMATIC",
  
  
  
  
"url": "https://acme.example.com/business",
  
  
  
  
"pricePeriod": {
  
  
  
  
  
"period": "month",
  
  
  
  
  
"time": 3
  
  
  
  
},
  
  
  
  
"discountPeriod": {
  
  
  
  
  
"period": "month",
  
  
  
  
  
"time": 3
  
  
  
  
},
  
  
  
  
"discountMonths": 6,
  
  
  
  
"trialDays": 14
  
  
  
}
  
  
],
  
  
"subscriptionsUrl": "https://acme.example.com/subscriptions.json",
  
  
"features": [
  
  
  
[
  
  
  
  
"Everything on acme.example.com"
  
  
  
]
  
  
],
  
  
"mainColor": "#3377fe",
  
  
"headline": "Get access to ACME Plus",
  
  
"description": "<p>Read every article, on every device.</p>",
  
  
"logoUrl": "https://assets.sesamy.com/vendor-assets/acme/logo.svg",
  
  
"footerPaymentMethods": [
  
  
  
[
  
  
  
  
"visa",
  
  
  
  
"mastercard",
  
  
  
  
"google-pay",
  
  
  
  
"apple-pay"
  
  
  
]
  
  
],
  
  
"singlePurchase": {
  
  
  
"enabled": true,
  
  
  
"title": "Buy Now",
  
  
  
"description": "One-time purchase",
  
  
  
"discountCode": "WELCOME20",
  
  
  
"discountId": "disc_acme_welcome"
  
  
},
  
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
  
"strategyId": "st_abc123"
  
},
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
"strategyId": "st_abc123"
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Deprecated

Register a read through a paywall strategy and grant access​

POST
/paywalls/strategies/{strategyId}/access

Executes the strategy to resolve the paywall for the visitor, then records the read against that paywall's leaky allowance exactly like POST /paywalls/{paywallId}/access. Returns a signed link when granted, or the resolved paywall when blocked. Signed-in readers also have the article counted in their daily/weekly article reads, only when access is granted.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

strategyId*

Unique identifier of the strategy

Type
string
Required
Example"st_abc123"

Request Body​

application/json
JSON
{
  
"attribution": {
  
  
"source": "google",
  
  
"medium": "cpc",
  
  
"campaign": "summer_sale",
  
  
"term": "running shoes",
  
  
"content": "logolink",
  
  
"referrer": "https://www.google.com/"
  
},
  
"content": {
  
  
"contentId": "string",
  
  
"title": "string",
  
  
"type": "string",
  
  
"price": 0,
  
  
"currency": "string",
  
  
"publisherId": "string",
  
  
"contentType": "NewsArticle",
  
  
"section": "sports",
  
  
"tags": [
  
  
  
[
  
  
  
  
"football",
  
  
  
  
"premier-league"
  
  
  
]
  
  
],
  
  
"authors": [
  
  
  
[
  
  
  
  
"Jane Doe"
  
  
  
]
  
  
],
  
  
"publishedAt": "2026-01-15T09:00:00.000Z"
  
},
  
"publisherContentId": "article-2024-01-15-news",
  
"url": "https://example.com/articles/my-article"
}

Responses​

Access result — either allowed with a signed link or blocked with the resolved paywall

application/json
JSON
{
  
"status": "string",
  
"signedLink": "https://example.com/articles/my-article?sesamy_token=eyJhbGciOiJFZERTQSJ9...",
  
"remaining": 2,
  
"paywallId": "string",
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
"strategyId": "st_abc123"
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Deprecated

Register a leaky paywall read and grant access​

POST
/paywalls/{paywallId}/access

Evaluates the configured leaky allowance. LOGIN grants require the signed content policy on the Capsule unlock endpoint. Returns a signed link when granted, or the paywall when blocked. Successful signed-in grants update article-read buckets. Use POST /access/check to test availability without consuming a read.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

paywallId*

Unique identifier of the paywall

Type
string
Required
Example"pw123456"

Request Body​

application/json
JSON
{
  
"publisherContentId": "article-2024-01-15-news",
  
"url": "https://example.com/articles/my-article"
}

Responses​

Access check result — either allowed with a signed link or blocked with paywall config

application/json
JSON
{
  
"status": "string",
  
"signedLink": "https://example.com/articles/my-article?sesamy_token=eyJhbGciOiJFZERTQSJ9...",
  
"remaining": 2
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Deprecated

Check leaky paywall availability without consuming a read​

POST
/paywalls/{paywallId}/access/check

Checks the configured leaky allowance without recording a read. Used to advertise availability; call POST /access to actually grant access and record the read.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

paywallId*

Unique identifier of the paywall

Type
string
Required
Example"pw123456"

Request Body​

application/json
JSON
{
  
"publisherContentId": "article-2024-01-15-news",
  
"url": "https://example.com/articles/my-article"
}

Responses​

Whether leaky access is available, with remaining count

application/json
JSON
{
  
"status": "allowed",
  
"remaining": 2,
  
"paywall": {
  
  
"id": "aM8o7LqpkGZJ-szyPwe_E",
  
  
"vendorId": "acme",
  
  
"currency": "SEK",
  
  
"version": 2,
  
  
"settings": {
  
  
  
"template": "BOXES",
  
  
  
"useDefaultLogo": true,
  
  
  
"useDefaultCurrency": true,
  
  
  
"useDefaultColor": true,
  
  
  
"styling": {
  
  
  
  
"dropShadow": true,
  
  
  
  
"backgroundColor": "#000000",
  
  
  
  
"showBackground": false
  
  
  
},
  
  
  
"displayOptions": {
  
  
  
  
"enableGift": true,
  
  
  
  
"enableCompany": true,
  
  
  
  
"enableLoginButton": true
  
  
  
},
  
  
  
"loginFields": {
  
  
  
  
"name": true
  
  
  
},
  
  
  
"leaky": {
  
  
  
  
"enabled": true,
  
  
  
  
"count": 3,
  
  
  
  
"periodInHours": 720
  
  
  
},
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
"redirectLabel": "Go to ACME",
  
  
  
"showPricesExVat": false
  
  
},
  
  
"showLoginButton": true,
  
  
"subscriptions": [
  
  
  
{
  
  
  
  
"id": "R4gX0YSbSU1WJA7bCrbQw",
  
  
  
  
"sku": "sid:acme-plus-monthly",
  
  
  
  
"poId": "VDuH_poxqIPKW638Ok43q",
  
  
  
  
"title": "ACME Plus monthly",
  
  
  
  
"description": "<p>Only 720 kr/year - save 20%</p>",
  
  
  
  
"price": 99,
  
  
  
  
"discountPrice": 75,
  
  
  
  
"discountCode": "WELCOME20",
  
  
  
  
"periodText": "3 months",
  
  
  
  
"comparePeriodText": "month",
  
  
  
  
"tag": "Most popular",
  
  
  
  
"selected": true,
  
  
  
  
"features": [
  
  
  
  
  
[
  
  
  
  
  
  
"Daily news",
  
  
  
  
  
  
"Exclusive interviews"
  
  
  
  
  
]
  
  
  
  
],
  
  
  
  
"buttonText": "BUY ACCESS",
  
  
  
  
"readMoreLink": "https://acme.example.com/subscriptions",
  
  
  
  
"readMoreText": "Read more",
  
  
  
  
"preferBusiness": false,
  
  
  
  
"redirectUrl": "https://acme.example.com/welcome",
  
  
  
  
"redirectLabel": "Start reading ACME Plus",
  
  
  
  
"discountId": "disc_acme_welcome",
  
  
  
  
"priceMode": "AUTOMATIC",
  
  
  
  
"url": "https://acme.example.com/business",
  
  
  
  
"pricePeriod": {
  
  
  
  
  
"period": "month",
  
  
  
  
  
"time": 3
  
  
  
  
},
  
  
  
  
"discountPeriod": {
  
  
  
  
  
"period": "month",
  
  
  
  
  
"time": 3
  
  
  
  
},
  
  
  
  
"discountMonths": 6,
  
  
  
  
"trialDays": 14
  
  
  
}
  
  
],
  
  
"subscriptionsUrl": "https://acme.example.com/subscriptions.json",
  
  
"features": [
  
  
  
[
  
  
  
  
"Everything on acme.example.com"
  
  
  
]
  
  
],
  
  
"mainColor": "#3377fe",
  
  
"headline": "Get access to ACME Plus",
  
  
"description": "<p>Read every article, on every device.</p>",
  
  
"logoUrl": "https://assets.sesamy.com/vendor-assets/acme/logo.svg",
  
  
"footerPaymentMethods": [
  
  
  
[
  
  
  
  
"visa",
  
  
  
  
"mastercard",
  
  
  
  
"google-pay",
  
  
  
  
"apple-pay"
  
  
  
]
  
  
],
  
  
"singlePurchase": {
  
  
  
"enabled": true,
  
  
  
"title": "Buy Now",
  
  
  
"description": "One-time purchase",
  
  
  
"discountCode": "WELCOME20",
  
  
  
"discountId": "disc_acme_welcome"
  
  
},
  
  
"decisionId": "6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f",
  
  
"strategyId": "st_abc123"
  
}
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


diagnostics​


Submit user diagnostics​

POST
/diagnostics

Submit diagnostic data for debugging purposes. Data is stored with user consent and can be retrieved by support staff.

Authorizations​

Basic
Type
HTTP (basic)
+
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"userId": "string",
  
"fallbackId": "string",
  
"timestamp": "string",
  
"pageUrl": "string",
  
"pageTitle": "string",
  
"profile": {
  
  
"additionalProperties": "string"
  
},
  
"entitlements": [
  
  
{
  
  
  
"additionalProperties": "string"
  
  
}
  
],
  
"contracts": [
  
  
{
  
  
  
"additionalProperties": "string"
  
  
}
  
],
  
"tags": [
  
  
"string"
  
],
  
"tallies": {
  
  
"additionalProperties": "string"
  
},
  
"browser": {
  
  
"userAgent": "string",
  
  
"platform": "string",
  
  
"language": "string",
  
  
"languages": [
  
  
  
"string"
  
  
],
  
  
"cookiesEnabled": true,
  
  
"onLine": true,
  
  
"hardwareConcurrency": 0,
  
  
"deviceMemory": 0,
  
  
"maxTouchPoints": 0,
  
  
"vendor": "string",
  
  
"viewportWidth": 0,
  
  
"viewportHeight": 0,
  
  
"screenWidth": 0,
  
  
"screenHeight": 0,
  
  
"pixelRatio": 0,
  
  
"colorDepth": 0,
  
  
"timezone": "string",
  
  
"timezoneOffset": 0
  
},
  
"detection": {
  
  
"adBlockEnabled": true,
  
  
"incognitoMode": true,
  
  
"inAppBrowser": true
  
},
  
"localStorage": [
  
  
{
  
  
  
"key": "string",
  
  
  
"value": "string",
  
  
  
"redacted": true
  
  
}
  
],
  
"sessionStorage": [
  
  
{
  
  
  
"key": "string",
  
  
  
"value": "string",
  
  
  
"redacted": true
  
  
}
  
],
  
"sdkVersion": "string",
  
"clientId": "string",
  
"errors": [
  
  
"string"
  
]
}

Responses​

Diagnostics stored successfully

application/json
JSON
{
  
"success": true,
  
"id": "string",
  
"timestamp": "string"
}

Playground​

Authorization
Body

Samples​


Get JWKS (JSON Web Key Set) for a vendor​

GET
/capsule/vendors/{vendorId}/.well-known/jwks.json

Returns the public keys used to verify Capsule token signatures for a specific vendor in JWKS format.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

vendorId*

The vendor identifier

Type
string
Required
Example"varldenom"

Responses​

JWKS containing public keys for token verification

application/json
JSON
{
  
"keys": [
  
  
{
  
  
  
"additionalProperties": "string"
  
  
}
  
]
}

Playground​

Authorization
Variables
Key
Value

Samples​


Deprecated

Unlock encrypted content​

POST
/capsule/vendors/{vendorId}/unlock

Unlocks encrypted Capsule content using the DCA unlock request format. Each keys entry carries a scope identifying the required access tier. Supports authenticated entitlements, pre-signed share tokens, and policies bound in a verified publisher resourceJWT (data.paywallUrl). Policy grants validate the resource scopes and record reads after key generation.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)
or

Parameters​

Path Parameters

vendorId*

The vendor identifier

Type
string
Required
Example"varldenom"

Request Body​

application/json
JSON
{
  
"resourceJWT": "string",
  
"keys": [
  
  
{
  
  
  
"contentName": "string",
  
  
  
"scope": "string",
  
  
  
"wrapKeys": [
  
  
  
  
{
  
  
  
  
  
"kid": "string",
  
  
  
  
  
"key": "string"
  
  
  
  
}
  
  
  
]
  
  
}
  
],
  
"shareToken": "string",
  
"paywall": "string",
  
"attribution": {
  
  
"source": "google",
  
  
"medium": "cpc",
  
  
"campaign": "summer_sale",
  
  
"term": "running shoes",
  
  
"content": "logolink",
  
  
"referrer": "https://www.google.com/"
  
}
}

Responses​

Derived keys for decrypting content

application/json
JSON
{
  
"keys": [
  
  
{
  
  
  
"contentName": "string",
  
  
  
"scope": "string",
  
  
  
"wrapKeys": [
  
  
  
  
{
  
  
  
  
  
"kid": "string",
  
  
  
  
  
"key": "string"
  
  
  
  
}
  
  
  
]
  
  
}
  
]
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Verify a Capsule signed token​

POST
/capsule/vendors/{vendorId}/verify

Verifies a Capsule-signed token (from a signed article link or the signedLink returned by paywall.hasAccess) using the vendor's signing key. Returns the decoded payload when the signature is valid and the token is not expired. No authentication is required — the token itself is the credential.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

vendorId*

The vendor identifier

Type
string
Required
Example"varldenom"

Request Body​

application/json
JSON
{
  
"token": "string"
}

Responses​

Verification result

application/json
JSON
{
  
"valid": true,
  
"message": "string",
  
"payload": {
  
  
"iss": "string",
  
  
"tier": "string",
  
  
"contentId": "string",
  
  
"tid": "string",
  
  
"iat": 0,
  
  
"exp": 0,
  
  
"url": "string",
  
  
"userId": "string",
  
  
"maxUses": 0,
  
  
"meta": {
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​


Initiate login​

GET
/auth/:clientId/login

Initiates the OAuth authorization code flow with PKCE. Redirects to the auth server.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

clientId*

OAuth client ID

Type
string
Required
Example"my-client-id"

Query Parameters

return_to

URL to redirect to after successful login: a relative path, or a URL on the same site (registrable domain) as the proxy. Anything else is refused with 400 INVALID_RETURN_TO.

Type
string
Example"https://www.example.com/article"
audience

The API audience to request

Type
string
Example"https://api.sesamy.com"
scope

Space-separated list of scopes

Type
string
Example"openid profile email offline_access"
prompt

OIDC prompt parameter forwarded to the auth server. Use "none" for a silent authentication attempt (e.g. migrating an existing SSO session) — the callback returns the user anonymously instead of erroring when no session exists.

Type
string
Example"none"
ui_locales

Space-separated list of preferred UI locales (BCP 47), forwarded to the auth server to localize the login screens.

Type
string
Example"sv en"
login_hint

OIDC login_hint forwarded to the auth server — the email to prefill on the login screen. The user can still authenticate as someone else; this is only a hint.

Type
string
Example"user@example.com"
session_transfer_token

AuthHero session transfer token forwarded to /authorize, which logs the reader in without a prompt. Comes from the fragment of a /auth/session-transfer redirect; use with prompt=none. Never stored in the login state.

Type
string
attribution

JSON-stringified attribution (UTM tags, referrer, etc.) forwarded as-is to the auth server so it can attribute the signup or login. Dropped if longer than 2048 characters.

Type
string
Example{"utmSource":"newsletter","utmCampaign":"spring"}
retry

Internal: marks an automatic retry triggered by a lost state cookie. Used to prevent infinite login loops.

Type
string

Responses​

Redirect to authorization server

Playground​

Authorization
Variables
Key
Value

Samples​


OAuth callback​

GET
/auth/:clientId/callback

Handles the OAuth callback, exchanges code for tokens, and sets cookies.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

clientId*

OAuth client ID

Type
string
Required
Example"my-client-id"

Query Parameters

code

Authorization code from auth server

Type
string
state

State parameter for CSRF protection

Type
string
error

Error code if authorization failed

Type
string
error_description

Human-readable error description

Type
string

Responses​

Redirect to return URL or home

Playground​

Authorization
Variables
Key
Value

Samples​


Logout​

GET
/auth/logout

Clears auth cookies and optionally redirects to auth server logout. Prefer GET /auth/{clientId}/logout so the auth server logout is reached even when the client hint cookie is unavailable.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

return_to

URL to redirect to after logout: a relative path, or a URL on the same site (registrable domain) as the proxy. Anything else is refused with 400 INVALID_RETURN_TO and the session is left as it was.

Type
string
Example"https://www.example.com"
local_only

Set to "true" to only clear local cookies without redirecting to the auth server. By default the auth server session is also cleared.

Type
string
Example"true"

Responses​

Redirect after logout

Playground​

Authorization
Variables
Key
Value

Samples​


Logout​

GET
/auth/:clientId/logout

Clears auth cookies and, unless local_only is set, redirects through the auth server logout. Mirrors /auth/{clientId}/login: taking the clientId from the path means the auth server logout is reached even when the client hint cookie is missing.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

clientId*

OAuth client ID

Type
string
Required
Example"my-client-id"

Query Parameters

return_to

URL to redirect to after logout: a relative path, or a URL on the same site (registrable domain) as the proxy. Anything else is refused with 400 INVALID_RETURN_TO and the session is left as it was.

Type
string
Example"https://www.example.com"
local_only

Set to "true" to only clear local cookies without redirecting to the auth server. By default the auth server session is also cleared.

Type
string
Example"true"

Responses​

Redirect after logout

Playground​

Authorization
Variables
Key
Value

Samples​


Get user info​

GET
/auth/userinfo

Returns information about the currently authenticated user from cookies.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

User information

application/json
JSON
{
  
"authenticated": true,
  
"sub": "string",
  
"exp": 0,
  
"scope": "string"
}

Playground​

Authorization

Samples​


Create a cookie session from an access token​

POST
/auth/{clientId}/session

Turns a bearer access token the caller already holds into the same HttpOnly cookie session the login callback issues, so cookie-mode (BFF) clients can adopt a token handed to them out of band — a deep link from a native app, an email link, a server-issued token. sesamy-js calls this for a #access_token= URL fragment. The token is verified against the token service JWKS before it is stored. No refresh token is involved: the session ends when the access token expires, and any refresh cookie from an earlier login on this browser is dropped so it cannot take over once that happens.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Path Parameters

clientId*

OAuth client ID (the vendor id). Must match the token's vendor.

Type
string
Required
Example"acme"

Responses​

Session cookies set. Same shape as /auth/userinfo.

application/json
JSON
{
  
"authenticated": true,
  
"sub": "string",
  
"exp": 0,
  
"scope": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​


Link Spotify (BFF token handoff)​

GET
/auth/spotify-link

Redirects the browser to the access-sync Spotify callback with the user's access token injected server-side. Used by sesamy-js in cookie/BFF mode, where the access token lives in an HttpOnly cookie and never enters client JS — only this proxy can decrypt it. Unauthenticated requests are bounced through the login flow and returned here afterwards.

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Query Parameters

sku*

Product SKU (subscription identifier) to link to Spotify

Type
string
Required
Example"sid:acme-plus-monthly"

Redirect to access-sync, or to login when unauthenticated

Authorization
Variables
Key
Value

Open a Sesamy page logged in (session transfer)​

GET
/auth/session-transfer

Redirects the browser to a Sesamy page (checkout, account, consume) and logs the reader in there. Used by sesamy-js in cookie/BFF mode for links built with sessionTransfer: true. The proxy exchanges the refresh token from the HttpOnly cookie for an AuthHero session transfer token at click time, so the token's 60 seconds start when the reader follows the link. The target receives #access_token=…&session_transfer_token=… in the URL fragment. Without a session, or when the exchange fails, the reader is sent on without the session transfer token.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

target*

Absolute URL of the Sesamy page to open. Must be one of the allowed Sesamy origins.

Type
string
Required
Example"https://checkout3.sesamy.com/?sku=sid%3Aacme-plus-monthly"
Format
"uri"

Responses​

Redirect to the target page

Playground​

Authorization
Variables
Key
Value

Samples​


support-session​


Generate support session token​

GET
/support-session

Generates a short-lived signed JWT for authenticating the current user with the support messenger.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Responses​

A signed support session token

application/json
JSON
{
  
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Playground​

Authorization

Samples​


licenses​


List the user's license keys​

GET
/licenses

Returns the user's most recently claimed key in the given pool, including expired keys (status=expired) so clients can offer a re-claim. Empty when nothing has been claimed yet. Read-only: never assigns a key.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Parameters​

Query Parameters

poolId*

The license key pool to look in. Publishers get the pool ID when creating the pool

Type
string
Required
Example"pool_8f3k2m"
Min Length
1
Max Length
128
Pattern
"^[a-zA-Z0-9_-]+$"

Responses​

The user's license keys in the pool

application/json
JSON
[
  
{
  
  
"key": "ACME1-FSEC2-3XY4Z-DEMO5",
  
  
"poolId": "pool_8f3k2m",
  
  
"claimedAt": "2026-07-01T09:30:00.000Z",
  
  
"expiresAt": "2027-07-01T09:30:00.000Z",
  
  
"status": "active"
  
}
]

Playground​

Authorization
Variables
Key
Value

Samples​


Claim a license key​

POST
/licenses/claim

Claims a key from the pool for the current user. Requires an active entitlement for the SKU configured on the pool. Idempotent: if the user already holds an unexpired key, that key is returned. After a key expires, calling claim again assigns a new one.

Authorizations​

OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)

Request Body​

application/json
JSON
{
  
"poolId": "pool_8f3k2m"
}

Responses​

The claimed license key

application/json
JSON
{
  
"key": "ACME1-FSEC2-3XY4Z-DEMO5",
  
"poolId": "pool_8f3k2m",
  
"claimedAt": "2026-07-01T09:30:00.000Z",
  
"expiresAt": "2027-07-01T09:30:00.000Z",
  
"status": "active"
}

Playground​

Authorization
Body

Samples​


Powered by VitePress OpenAPI

Interactive API Documentation

This is the complete OpenAPI specification for the Sesamy API. You can explore all endpoints, request/response schemas, and try out API calls directly from this page.

About This API ​

The Sesamy API provides comprehensive endpoints for managing content monetization, subscriptions, and user entitlements.

For additional guides and examples, check out:

Released under the MIT License.