API Reference

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

API Overview

Sesamy offers two main API groups:

Client API

For end-user facing operations and content access control.

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

Use cases:

• User authentication and profiles
• Content access verification
• Subscription management
• Payment processing
• Entitlement checks

Explore Client API →

Management API

For administrative operations and backend management.

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

Use cases:

• User management
• Vendor configuration
• Product and pricing management
• Analytics and reporting
• Bulk operations

Explore Management API →

API Fundamentals

Base URLs

Environment	Client API	Management API
Production	https://api2.sesamy.com	https://api2.sesamy.com/management
Staging	https://staging-api.sesamy.com	https://staging-api.sesamy.com/management

Request Format

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

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

The JWT token includes:

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

Response Format

All responses are in JSON format:

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

Error Responses

Errors follow a consistent format:

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

Common Patterns

Pagination

List endpoints support pagination:

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

Response includes pagination metadata:

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

Filtering

Filter results with query parameters:

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

Sorting

Sort results using the sort parameter:

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

Use - prefix for descending order.

HTTP Status Codes

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

Versioning

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

Example endpoints:

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

Rate Limits

See Rate Limits for detailed information.

Error Handling

See Error Handling for comprehensive error handling guides.

OpenAPI Specification

Access the complete OpenAPI specifications:

• Client API OpenAPI Spec
• Management API OpenAPI Spec

Interactive API Explorer

Try the APIs in your browser:

• Client API Explorer
• Management API Explorer

Next Steps

• Client API - End-user operations
• Management API - Administrative operations
• Rate Limits - Understand rate limiting
• Error Handling - Handle errors gracefully