OpenAPI Specification
Servers
https://api2.sesamy.comCurrent environment
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": [ { "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, "willCancelAt": "string", "cancelRequestedAt": "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 } }
[
]
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
Requiredstring
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": [ { "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, "willCancelAt": "string", "cancelRequestedAt": "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 }
{
}
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
Requiredstring
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" ] } ] }
[
]
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
Requiredstring
Example
"1d78271264b9c76d5842911dd70b4353"Request Body
application/json
JSON "reason": "string", "comment": "string"
{
}
Responses
Contract cancelled successfully
application/json
JSON "success": true
{
}
Create an amendment
POST
/contracts/{contract_id}/amendments
Creates a new amendment for a contract, such as applying a discount code.
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
Requiredstring
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": [ { "code": "string", "status": "string", "id": "string", "name": "string", "description": "string" } ], "amendmentType": "string", "nextBill": { "total": 0, "currency": "string", "date": "string" }
{
}
Confirm an amendment
POST
/contracts/{contract_id}/amendments/{amendment_id}/confirm
Confirms a pending amendment for a contract.
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
Requiredstring
Example
"1d78271264b9c76d5842911dd70b4353"amendment_id*
The unique identifier of the amendment
Type
Requiredstring
Example
"amendment123"Responses
Amendment confirmed successfully
application/json
JSON "success": true
{
}
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" }
[
]
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
Requiredstring
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"
{
}
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
Type
string
Valid values
"article""audiobook""ebook""bundle""podcast""pass""publication""physical_issue"Example
"article"sku
Type
string
Example
"premium-article-123"purchase-option-id
Type
string
Example
"one-time"wait-for-entitlement-after
If specified the api will wait until an entitlement after this timestamp is available before it returns
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, "createdAt": "string", "updatedAt": "string", "token": "string", "expiresAt": "string" }
[
]
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
Requiredstring
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, "createdAt": "string", "updatedAt": "string", "token": "string", "expiresAt": "string"
{
}
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
Requiredstring
Example
"1d78271264b9c76d5842911dd70b4353"Responses
Access information for the entitlement
application/json
JSON "id": "string", "url": "string", "token": "string", "title": "string", "filename": "string", "type": "string"
{
}
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
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" }
[
]
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" }
[
]
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
Requiredstring
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"
{
}
Get all user metadata
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
Requiredstring
Example
"preferences"Request Body
text/plain
JSON
"string"
Responses
Metadata value set successfully
application/json
JSON "success": true
{
}
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
Requiredstring
Example
"preferences"Responses
Metadata value deleted successfully
application/json
JSON "success": true
{
}
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" ]
{
}
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
Requiredstring
Example
"test"Responses
The tally value for the specified ID
application/json
JSON "string"
[
]
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
Requiredstring
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"
{
}
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
Requiredstring
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"
[
]
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*
Type
Requiredstring
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 }
[
]
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
Requiredstring
Example
"item123"Request Body
application/json
JSON "sku": "magazine-april-2023"
{
}
Responses
Delivery request result
application/json
JSON "ok": true
{
}
List user tags
Add a tag
Delete a tag
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"
{
}
Delete own profile
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"
{
}
Check Spotify link status
Unlink Spotify account
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
Requiredstring
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"
{
}
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
Requiredstring
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, "createdAt": "string", "updatedAt": "string", "token": "string", "expiresAt": "string" }
[
]
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" }
[
]
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*
Type
Requiredstring
Example
"https://www.example.com/article"selector
Type
string
Example
".article-content"cache
Type
string
Example
"true"Responses
The unlocked content
text/html
JSON
"string"
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", "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 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", "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"
{
}
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
Requiredstring
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", "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"
{
}
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
Requiredstring
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", "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", "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"
{
}
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"
{
}
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" }
[
]
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.
Authorizations
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)
Parameters
Path Parameters
paywallId*
Type
Requiredstring
Example
"pw123456"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" }, "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", "url": "https://acme.example.com/business" } ], "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" }
{
}
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*
Type
Requiredstring
Example
"str_abc123"Query Parameters
debug
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" }, "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" }, "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", "url": "https://acme.example.com/business" } ], "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" } }, "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" } }
{
}
Register a leaky paywall read and grant access
POST
/paywalls/{paywallId}/access
Records a read against the leaky paywall allowance and returns a signed link if access is granted, or the paywall configuration if the free article limit has been reached. 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*
Type
Requiredstring
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
{
}
Check leaky paywall availability without consuming a read
POST
/paywalls/{paywallId}/access/check
Evaluates whether the reader currently has leaky paywall access for an article 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*
Type
Requiredstring
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" }, "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", "url": "https://acme.example.com/business" } ], "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" } }
{
}
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"
{
}
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
Requiredstring
Example
"varldenom"Responses
JWKS containing public keys for token verification
application/json
JSON "keys": [ { "additionalProperties": "string" } ]
{
}
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 users with entitlements and pre-signed share tokens.
Authorizations
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)
or
Parameters
Path Parameters
vendorId*
The vendor identifier
Type
Requiredstring
Example
"varldenom"Request Body
application/json
JSON "resourceJWT": "string", "keys": [ { "contentName": "string", "scope": "string", "wrapKeys": [ { "kid": "string", "key": "string" } ] } ], "shareToken": "string"
{
}
Responses
Derived keys for decrypting content
application/json
JSON "keys": [ { "contentName": "string", "scope": "string", "wrapKeys": [ { "kid": "string", "key": "string" } ] } ]
{
}
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
Requiredstring
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" } }
{
}
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*
Type
Requiredstring
Example
"my-client-id"Query Parameters
return_to
Type
string
Example
"https://app.example.com/dashboard"audience
Type
string
Example
"https://api.sesamy.com"scope
Type
string
Example
"openid profile email offline_access"prompt
Type
string
Example
"none"ui_locales
Type
string
Example
"sv en"login_hint
Type
string
Example
"user@example.com"retry
Type
string
Responses
Redirect to authorization server
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*
Type
Requiredstring
Example
"my-client-id"Query Parameters
code
Type
string
state
Type
string
error
Type
string
error_description
Type
string
Responses
Redirect to return URL or home
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
Type
string
Example
"https://app.example.com"local_only
Type
string
Example
"true"Responses
Redirect after logout
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*
Type
Requiredstring
Example
"my-client-id"Query Parameters
return_to
Type
string
Example
"https://app.example.com"local_only
Type
string
Example
"true"Responses
Redirect after logout
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"
{
}
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*
Type
Requiredstring
Example
"acme"Responses
Session cookies set. Same shape as /auth/userinfo.
application/json
JSON "authenticated": true, "sub": "string", "exp": 0, "scope": "string"
{
}
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.
Authorizations
OpenID
Type
OpenID Connect (https://token.sesamy.com/.well-known/openid-configuration)
Parameters
Query Parameters
sku*
Type
Requiredstring
Example
"sid:acme-plus-monthly"Responses
Redirect to access-sync, or to login when unauthenticated
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..."
{
}
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*
Type
Requiredstring
Example
"pool_8f3k2m"Min Length
1Max Length
128Pattern
"^[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" }
[
]
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"
{
}
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:
- Getting Started - Quick start guide
- Authentication - Authentication methods
- Client API Guide - Client API overview
- Management API Guide - Management API overview
- SDKs - Official client libraries