License API

This page defines the redemption-code licensing API your app must expose so App Store can fulfill purchases. Implement these endpoints so customers receive access without NewRich storing pre-generated passwords.

API version: v1
Base path: /api/v1
Content type: application/json
Authentication: Caller domain allowlist + X-Licensing-Api-Key (see below)

Endpoints App Store calls

App Store stores the full versioned API root per product (for example https://dashboard.yourapp.com/api/v1) and appends resource paths:

One-time vs recurring offerings

Each marketplace app is either all one-time or all subscription. Recurring plans on the same app may still use different cadences (monthly, quarterly, 6 months, annual).

App Store tells your API which model applies on every licensing POST via additive fields:

Treat these fields as required going forward. Older integrations that only read email / order_id / product_sku continue to work for issue, but you must accept the recurrence fields to support subscription offerings correctly.

Authenticate App Store requests

Apply both checks below on all four licensing endpoints before processing the request body.

License API key

App Store sends a shared secret on every request. Your API must reject requests with a missing or incorrect key.

Request header: X-Licensing-Api-Key

Your configuration:

LICENSING_API_KEY=<provided privately by NewRich>

Compare the header value to your configured key using a constant-time comparison.

Caller domain allowlist

Your API must also reject requests that do not come from an authorized App Store hostname.

Your configuration:

LICENSING_ALLOWED_DOMAINS=apps.newrich.com

App Store production requests identify themselves with hostname apps.newrich.com.

Resolve the caller hostname

Read the caller in this order (first match wins):

1. X-Licensing-Caller-Domain — preferred for server-to-server calls from App Store
2. Origin — hostname extracted from the URL
3. Referer — hostname extracted from the URL

Expect a hostname only (apps.newrich.com), not a full URL. Normalize case and strip ports when comparing.

Reject invalid callers

Response envelope

Use the same JSON shape on all licensing endpoints.

Success:

{
  "success": true,
  "msg": "ok",
  "data": { }
}

Application error:

{
  "success": false,
  "msg": "Human-readable error message"
}

Validation error (HTTP 422):

{
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Shared request fields

App Store sends this identity + recurrence body on generate, renew, revoke, and reactivate. Lookup keys are email + order_id (plus optional product_sku).

POST /redemption_codes — Generate

Issue an email-bound redemption code after purchase.

Request body (one-time)

POST /api/v1/redemption_codes HTTP/1.1
Host: dashboard.yourapp.com
Content-Type: application/json
X-Licensing-Caller-Domain: apps.newrich.com
X-Licensing-Api-Key: <your-license-api-key>

{
  "email": "[email protected]",
  "order_id": "NR-42-17",
  "product_sku": "yourapp-pro",
  "access_duration": "lifetime",
  "billing_interval": null,
  "term": "lifetime"
}

Request body (subscription)

{
  "email": "[email protected]",
  "order_id": "NR-42-17",
  "product_sku": "yourapp-pro",
  "access_duration": "subscription",
  "billing_interval": "monthly",
  "term": "monthly"
}

Minimum success response (HTTP 2xx):

{
  "success": true,
  "data": {
    "code": "YOUR-ABCD-EFGH-IJKL"
  }
}

App Store requires HTTP 2xx, "success": true (boolean), and a non-empty string data.code. A fuller response is fine:

{
  "success": true,
  "msg": "ok",
  "data": {
    "code": "YOUR-ABCD-EFGH-IJKL",
    "email": "[email protected]",
    "order_id": "NR-42-17",
    "status": "pending",
    "current_upgrade": "Pro"
  }
}

Behavior

• Idempotent on order_id: duplicate generate calls return the same code (HTTP 200).
• Revoked order: if the order was revoked, generate returns HTTP 409 with msg: "Order has been revoked."
• Code format: your choice; reference apps use a prefixed alphanumeric format.
• status: start as pending until the customer registers.
• Recurring: store access_duration, billing_interval, and term with the issued code so renew / revoke can apply the correct access rules.

POST /redemption_codes/renew — Renew

Extend access after a paid subscription period. App Store calls this for recurring offerings when a period is renewed.

Request body

{
  "email": "[email protected]",
  "order_id": "NR-42-17",
  "product_sku": "yourapp-pro",
  "access_duration": "subscription",
  "billing_interval": "monthly",
  "term": "monthly",
  "period_ends_at": "2026-10-04T00:00:00Z"
}

Success: HTTP 2xx with "success": true. data.code is not required.

Behavior

• Locate the license by order_id (and email as needed).
• Extend or refresh the customer’s access for another billing period.
• If period_ends_at is present, persist it as the authoritative period end.
• Idempotent for the same renewal window when practical (safe to retry).

POST /redemption_codes/revoke — Revoke

Disable a code or linked user account (refunds, cancellations, past-due subscriptions).

Request body

{
  "email": "[email protected]",
  "order_id": "NR-42-17",
  "product_sku": "yourapp-pro",
  "access_duration": "subscription",
  "billing_interval": "monthly",
  "term": "monthly",
  "reason": "refunded"
}

App Store always sends the shared identity + recurrence fields. reason is included when available (for example "refunded", "cancelled", "past_due").

For local tooling you may also accept { "code": "YOUR-ABCD-EFGH-IJKL" } (code case-insensitive), but production App Store calls use email + order_id.

Success (200) — "success": true. Optional data matching generate is fine.

POST /redemption_codes/reactivate — Reactivate

Restore a previously revoked code or account.

Request body — same shared fields as revoke (including optional reason, for example "paid").

Redemption code lifecycle

stateDiagram-v2
    [*] --> pending: POST /redemption_codes
    pending --> redeemed: Customer registers
    pending --> revoked: POST .../revoke
    redeemed --> revoked: POST .../revoke
    redeemed --> redeemed: POST .../renew (subscription)
    revoked --> pending: POST .../reactivate (never redeemed)
    revoked --> redeemed: POST .../reactivate (was redeemed)

Customer registration (your app)

Deliver the code from generate to the purchaser (App Store includes it in the order confirmation email). The customer completes registration at your public registration page.

Enforce at registration:

• Code must exist and be pending
• Email must match the email sent to generate (case-insensitive)
• Code is one-time use for registration
• Revoked codes are rejected

This step is outside the license API. App Store never calls a validate or activate endpoint.

For subscription codes, grant access according to billing_interval / term, and keep renewing or revoking that access when App Store calls those endpoints later.

Implementation checklist

• X-Licensing-Api-Key validation on all four routes (LICENSING_API_KEY, constant-time compare)
• Caller domain allowlist on all four routes (LICENSING_ALLOWED_DOMAINS)
• POST /api/v1/redemption_codes accepting email, order_id, optional product_sku, plus access_duration, billing_interval, term
• Unique order_id constraint and idempotent generate
• HTTP 409 when re-generating a revoked order
• POST .../renew extending subscription access (honor period_ends_at when present)
• POST .../revoke and POST .../reactivate keyed by email + order_id (optional reason)
• Disable linked user / access on revoke; re-enable on reactivate
• Persist recurrence fields so renew/revoke apply the correct access model
• Public registration page with email-bound, one-time code redemption
• Share license API base URL and customer app URL with NewRich for listing setup

Before go-live

NewRich verifies your integration before your listing goes live — authentication, code generation, idempotency, registration, renew/revoke/reactivate, and an end-to-end purchase. During marketplace onboarding, the team will share a private verification checklist and test steps for your endpoints. Do not publish license API keys or ad-hoc test commands in public documentation or support channels.

Related

• Marketplace overview — roles and end-to-end flow