API Reference

The AppActor REST API. Base URL: https://api.appactor.com

Authentication

• Public keys (pk_*): client SDK endpoints
• Secret keys (sk_*): admin/server-to-server endpoints

Use one of:

Authorization: Bearer <key>

or

X-API-Key: <key>

Response Format

Most endpoints return this envelope:

// Success
{ "data": { "...": "..." }, "requestId": "req_abc123" }

// Error
{ "error": { "code": "ERROR_CODE", "message": "..." }, "requestId": "req_abc123" }

Exception: POST /v1/payment/receipts/apple returns the SDK receipt-status contract (ok, retryable_error, permanent_error) instead of the generic envelope.

Client SDK Endpoints (pk_* key)

Identity

POST /v1/payment/identify

Create or retrieve a user identity and return customer snapshot.

{
  "appUserId": "user_123",
  "platform": "ios",
  "appVersion": "2.1.0",
  "sdkVersion": "1.0.0",
  "deviceLocale": "en_US",
  "deviceModel": "iPhone15,2",
  "osVersion": "17.0"
}

POST /v1/payment/login

Switch from current user to a new user.

{
  "currentAppUserId": "appactor-anon-abc",
  "newAppUserId": "user_123"
}

POST /v1/payment/logout

Logout current user.

{
  "appUserId": "user_123"
}

Offerings

GET /v1/payment/offerings

Fetch server-driven offerings. Supports ETag / If-None-Match.

Customer Info

GET /v1/customers/:appUserId

Fetch customer entitlements/subscriptions for the given app user ID. Supports ETag / If-None-Match.

Receipts

POST /v1/payment/receipts/apple

Submit Apple StoreKit 2 signed transaction (signedTransactionInfo) for validation.

{
  "appUserId": "user_123",
  "bundleId": "com.myapp.app",
  "signedTransactionInfo": "<JWS string>",
  "environment": "production"
}

Response status contract:

Status	Meaning	SDK behavior
ok	Receipt validated	Finish transaction
retryable_error	Temporary/transient failure	Keep queued and retry
permanent_error	Invalid/revoked/malformed receipt	Finish and discard

POST /v1/payment/restore

Restore purchases by submitting transactions/purchases.

{
  "appUserId": "user_123",
  "store": "apple",
  "transactions": [
    {
      "transactionId": "12345",
      "jwsRepresentation": "<JWS string>"
    }
  ]
}

Remote Config

GET /v1/remote-config

Resolve active config values for the authenticated app context.

Query parameters:

Parameter	Required	Description
app_user_id	No	User ID for entitlement-based targeting
app_version	No	App version for version targeting
country	No	ISO 3166-1 alpha-2 country code

Experiments

POST /v1/experiments/:experimentKey/assignments

Assign (or return sticky assignment for) a user in an experiment.

Query parameters:

Parameter	Required	Description
app_user_id	Yes	User ID (max 256 chars)
app_version	No	App version for targeting
country	No	ISO 3166-1 alpha-2 country code

Apple Search Ads

POST /v1/asa/attribution

Submit ASA attribution token payload.

POST /v1/asa/purchase-event

Submit ASA purchase event payload.

Server-Side Endpoints (sk_* key)

User Management

GET /v1/api/users/:id

Get user details.

DELETE /v1/api/users/:id

Soft-delete a user.

PUT /v1/api/users/:id/attributes

Patch/replace user attributes.

{
  "attributes": {
    "plan": "enterprise",
    "seats": 50,
    "trial": false
  }
}

Entitlement Management

POST /v1/api/users/:id/entitlements/:entitlementId/grant

Grant entitlement directly (promotional/manual).

{
  "duration": "P30D"
}

Or:

{
  "endTimeMs": 1706745600000
}

POST /v1/api/users/:id/entitlements/:entitlementId/revoke

Revoke manually granted entitlement.

ASA Identity Sync

POST /v1/asa/update-user-id

Server-to-server ASA identity update endpoint (requires secret key).

Webhook Endpoints

POST /v1/webhooks/apple/:token

Inbound Apple App Store Server Notifications V2.

POST /v1/webhooks/google/:appId

Inbound Google Play Pub/Sub notifications.

Error Codes

Code	HTTP Status	Description
VALIDATION_ERROR	400	Invalid request payload/params
UNAUTHORIZED	401	Invalid/missing API key
NOT_FOUND	404	Resource not found
CONFLICT	409	Conflict (e.g., identity collision)
RATE_LIMIT_EXCEEDED	429	Request throttled
INTERNAL	500	Internal server error

Health Check

GET /health

Service health endpoint (no authentication required).

{
  "status": "ok",
  "timestamp": "2025-01-15T12:00:00Z"
}

Next Steps

• API Authentication — Key types and security model
• Webhooks — Subscription event integration