Tuish API

The Tuish API is a REST API hosted on Cloudflare Workers. It powers the SDK's checkout, authentication, and license management features.

Note: You typically don't call these endpoints directly. The SDK handles all API communication. This reference is for understanding how the system works or building custom integrations.

Base URL

https://api.tuish.dev/v1

Interactive Reference

View the full OpenAPI spec here: API Reference.

How SDK and API Connect

┌──────────────────────────────────────────────────────────────┐
│                        YOUR APP                               │
│                           │                                   │
│                    ┌──────▼──────┐                           │
│                    │  @tuish/sdk │                           │
│                    └──────┬──────┘                           │
│                           │                                   │
└───────────────────────────┼───────────────────────────────────┘
                            │ HTTPS
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                      TUISH API                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │  /checkout  │  │   /auth     │  │  /purchase  │          │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
│         │                │                │                   │
│         └────────────────┼────────────────┘                   │
│                          ▼                                    │
│                    ┌───────────┐                              │
│                    │  Stripe   │                              │
│                    │  Connect  │                              │
│                    └─────┬─────┘                              │
│                          │                                    │
└──────────────────────────┼────────────────────────────────────┘
                           ▼
                    Your Stripe Account

Authentication

Two authentication methods are used:

Method	Header	Used For
API Key	`X-API-Key: tuish_sk_...`	Developer operations, first-time purchases
Bearer Token	`Authorization: Bearer ...`	Returning customer purchases

Endpoint Groups

Developer Management

For CLI operations (tuish signup, tuish connect, tuish products):

Method	Path	Auth	Description
POST	`/developers/signup`	None	Create developer account
GET	`/connect/status`	API Key	Check Stripe connection
POST	`/connect/start`	API Key	Start Stripe OAuth flow
GET	`/connect/callback`	None	OAuth callback
POST	`/developers/products`	API Key	Create product
GET	`/developers/products`	API Key	List products
PATCH	`/developers/products/:id`	API Key	Update product

Checkout (Browser Flow)

Called by sdk.purchaseInBrowser():

Method	Path	Auth	Description
POST	`/checkout/init`	API Key	Create Stripe checkout session
GET	`/checkout/status/:id`	None	Poll for completion
GET	`/checkout/success`	None	Success redirect
GET	`/checkout/cancel`	None	Cancel redirect

Authentication (Terminal Flow)

Called by sdk.purchaseInTerminal() - login phase:

Method	Path	Auth	Description
POST	`/auth/login/init`	None	Request OTP via SMS
POST	`/auth/login/verify`	None	Verify OTP, get identity token

Purchase (Terminal Flow)

Called by sdk.purchaseInTerminal() - purchase phase:

Method	Path	Auth	Description
POST	`/purchase/init`	Bearer	Get saved cards, amount
POST	`/purchase/otp`	Bearer	Request confirmation OTP
POST	`/purchase/confirm`	Bearer	Confirm with OTP, charge card

License Validation

Called by sdk.checkLicense() for cache refresh:

Method	Path	Auth	Description
POST	`/licenses/validate`	API Key	Validate license online

Webhooks

Stripe sends events here after payments:

Method	Path	Auth	Description
POST	`/webhooks/stripe`	Stripe Signature	Handle payment events

Complete Flow Example

Browser checkout (what the SDK does internally):

# 1. Create checkout session
curl -X POST "$API/checkout/init" \
  -H "X-API-Key: tuish_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"productId": "prod_abc123"}'
# → { "sessionId": "cs_...", "checkoutUrl": "https://checkout.stripe.com/..." }

# 2. Customer pays in browser...

# 3. Poll for completion
curl "$API/checkout/status/cs_..."
# → { "status": "complete", "license": { ... } }

Next Steps

Checkout API - Request/response details for checkout
Authentication API - OTP-based customer login
Licenses API - License validation and format
Complete Integration Guide - End-to-end walkthrough

API Overview