{"openapi":"3.1.0","info":{"title":"AppScore API","version":"1.0.0","summary":"Application & subscription management core for Apple App Store and Google Play.","description":"AppScore is a multi-tenant core for managing your company's mobile applications and\ntheir **subscriptions** across the Apple App Store and Google Play, following each\nstore's server-side standards (App Store Server API & Notifications V2, Google Play\nDeveloper API & Real-Time Developer Notifications).\n\n## Authentication\n\nTwo credential types:\n\n- **Management API** — `Authorization: Bearer <token>` using a Sanctum token\n  (created via `/auth/register`, `/auth/login`, or `/auth/tokens`). A token with\n  broad abilities can be given to an AI agent to provision and operate everything.\n- **Client/SDK API** (`/client/*`) — `Authorization: Bearer app_pk_...` using an\n  app's public SDK key.\n\nPass `X-Tenant: <slug-or-uuid>` to select a workspace when your account has more\nthan one (otherwise the default/first workspace is used).\n\n## Idempotent provisioning\n\n`POST /bootstrap` creates or updates an entire app — entitlements, products,\nofferings and packages — in a single, repeatable call.","contact":{"name":"AppScore","url":"https://appscore.aramin.co"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://appscore.aramin.co/api/v1","description":"Production"}],"tags":[{"name":"Authentication","description":"Account registration, login and API tokens."},{"name":"Tenants","description":"Workspaces that isolate apps and data."},{"name":"Apps","description":"Applications managed within a tenant."},{"name":"Credentials","description":"Apple/Google store credentials per app."},{"name":"Products","description":"Store products (subscriptions & IAPs)."},{"name":"Entitlements","description":"Logical access levels unlocked by products."},{"name":"Offerings","description":"Presented sets of packages."},{"name":"Packages","description":"Purchasable units inside an offering."},{"name":"Customers","description":"End users (subscribers) of an app."},{"name":"Subscriptions","description":"Subscription state and history."},{"name":"Transactions","description":"Individual purchase/renewal records."},{"name":"Events","description":"Domain event feed."},{"name":"Webhooks","description":"Outbound webhook endpoints."},{"name":"Bootstrap","description":"One-shot provisioning for AI/IaC."},{"name":"Client","description":"SDK/client endpoints (app public key auth)."},{"name":"Stores","description":"Inbound Apple/Google server notifications."}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Sanctum personal access token (management API)."},"appKey":{"type":"http","scheme":"bearer","description":"App public SDK key (app_pk_...) for /client endpoints."}},"parameters":{"TenantHeader":{"name":"X-Tenant","in":"header","required":false,"schema":{"type":"string"},"description":"Workspace slug or uuid to scope the request."},"AppUuid":{"name":"app","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}},"Tenant":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"billing_email":{"type":"string","nullable":true},"plan":{"type":"string","enum":["free","pro","enterprise"]}}},"App":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"bundle_id":{"type":"string","nullable":true},"package_name":{"type":"string","nullable":true},"platforms":{"type":"array","items":{"type":"string"}},"public_api_key":{"type":"string"},"status":{"type":"string","enum":["active","paused","archived"]}}},"Product":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"store":{"type":"string","enum":["apple","google","stripe","custom"]},"identifier":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["subscription","non_renewing_subscription","consumable","non_consumable"]},"subscription_period":{"type":"string","nullable":true,"example":"P1M"},"price":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true}}},"Entitlement":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"identifier":{"type":"string","example":"premium"},"name":{"type":"string"},"product_identifiers":{"type":"array","items":{"type":"string"}}}},"Offering":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"identifier":{"type":"string","example":"default"},"is_current":{"type":"boolean"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"}}}},"Package":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"identifier":{"type":"string","example":"$rc_monthly"},"package_type":{"type":"string","enum":["monthly","annual","weekly","two_month","three_month","six_month","lifetime","custom"]},"product_identifier":{"type":"string"}}},"Subscriber":{"type":"object","properties":{"app_user_id":{"type":"string"},"is_anonymous":{"type":"boolean"},"entitlements":{"type":"object","additionalProperties":true},"subscriptions":{"type":"object","additionalProperties":true}}},"Subscription":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"store":{"type":"string"},"product_identifier":{"type":"string"},"status":{"type":"string","enum":["active","trialing","in_grace_period","on_hold","paused","canceled","expired","revoked","in_billing_retry","paused_pending","unknown"]},"is_active":{"type":"boolean"},"expires_date":{"type":"string","format":"date-time","nullable":true}}}}},"paths":{"/health":{"get":{"tags":["Stores"],"summary":"Health check","responses":{"200":{"description":"Service status","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}},"/auth/register":{"post":{"tags":["Authentication"],"summary":"Register an account + first workspace","responses":{"201":{"description":"Created with token","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"tenant_name":{"type":"string"}},"required":["name","email","password"]}}}},"security":[]}},"/auth/login":{"post":{"tags":["Authentication"],"summary":"Login and receive a token","responses":{"200":{"description":"Token issued","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]}}}},"security":[]}},"/auth/me":{"get":{"tags":["Authentication"],"summary":"Current user, roles and tenants","responses":{"200":{"description":"User profile","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/auth/tokens":{"post":{"tags":["Authentication"],"summary":"Create an additional API token (e.g. for an AI agent)","responses":{"201":{"description":"Token issued","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"abilities":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/auth/logout":{"post":{"tags":["Authentication"],"summary":"Revoke the current token","responses":{"200":{"description":"Logged out","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/tenants":{"get":{"tags":["Tenants"],"summary":"List your tenants","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tenant"}}}}}}}}},"post":{"tags":["Tenants"],"summary":"Create a tenant","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tenant"}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string"}},"required":["name"]}}}}}},"/tenants/{tenant}":{"get":{"tags":["Tenants"],"summary":"Get a tenant","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tenant"}}}}}}},"parameters":[{"name":"tenant","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Tenants"],"summary":"Update a tenant","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tenant"}}}}}}},"parameters":[{"name":"tenant","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Tenants"],"summary":"Delete a tenant","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"name":"tenant","in":"path","required":true,"schema":{"type":"string"}}]}},"/apps":{"get":{"tags":["Apps"],"summary":"List apps in the active tenant","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/App"}}}}}}}},"parameters":[{"$ref":"#/components/parameters/TenantHeader"}]},"post":{"tags":["Apps"],"summary":"Create an app","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/App"}}}}}}},"parameters":[{"$ref":"#/components/parameters/TenantHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"bundle_id":{"type":"string"},"package_name":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/apps/{app}":{"get":{"tags":["Apps"],"summary":"Get an app","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/App"}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]},"patch":{"tags":["Apps"],"summary":"Update an app","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/App"}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]},"delete":{"tags":["Apps"],"summary":"Delete an app","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]}},"/apps/{app}/rotate-key":{"post":{"tags":["Apps"],"summary":"Rotate the public SDK key","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/App"}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]}},"/apps/{app}/credentials":{"get":{"tags":["Credentials"],"summary":"List store credentials","responses":{"200":{"description":"Credential list","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]},"post":{"tags":["Credentials"],"summary":"Add/replace Apple or Google credentials","responses":{"201":{"description":"Saved","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["apple","google"]},"environment":{"type":"string","enum":["production","sandbox"]},"apple_issuer_id":{"type":"string"},"apple_key_id":{"type":"string"},"apple_private_key":{"type":"string"},"apple_bundle_id":{"type":"string"},"google_package_name":{"type":"string"},"google_service_account_json":{"type":"string"}},"required":["platform"]}}}}}},"/apps/{app}/products":{"get":{"tags":["Products"],"summary":"List products","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]},"post":{"tags":["Products"],"summary":"Create a product","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"store":{"type":"string","enum":["apple","google","stripe","custom"]},"identifier":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"subscription_period":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"entitlements":{"type":"array","items":{"type":"string"}}},"required":["store","identifier","name","type"]}}}}}},"/products/{product}":{"get":{"tags":["Products"],"summary":"Get a product","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"type":"string"}}]},"patch":{"tags":["Products"],"summary":"Update a product","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Products"],"summary":"Delete a product","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"name":"product","in":"path","required":true,"schema":{"type":"string"}}]}},"/apps/{app}/entitlements":{"get":{"tags":["Entitlements"],"summary":"List entitlements","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Entitlement"}}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]},"post":{"tags":["Entitlements"],"summary":"Create an entitlement","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Entitlement"}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"identifier":{"type":"string"},"name":{"type":"string"},"product_identifiers":{"type":"array","items":{"type":"string"}}},"required":["identifier","name"]}}}}}},"/entitlements/{entitlement}":{"patch":{"tags":["Entitlements"],"summary":"Update an entitlement","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Entitlement"}}}}}}},"parameters":[{"name":"entitlement","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"tags":["Entitlements"],"summary":"Delete an entitlement","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"name":"entitlement","in":"path","required":true,"schema":{"type":"string"}}]}},"/apps/{app}/offerings":{"get":{"tags":["Offerings"],"summary":"List offerings","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Offering"}}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]},"post":{"tags":["Offerings"],"summary":"Create an offering","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Offering"}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"identifier":{"type":"string"},"is_current":{"type":"boolean"}},"required":["identifier"]}}}}}},"/offerings/{offering}/packages":{"get":{"tags":["Packages"],"summary":"List packages","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Package"}}}}}}}},"parameters":[{"name":"offering","in":"path","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Packages"],"summary":"Create a package","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Package"}}}}}}},"parameters":[{"name":"offering","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_identifier":{"type":"string"},"identifier":{"type":"string"},"package_type":{"type":"string"}},"required":["product_identifier","identifier","package_type"]}}}}}},"/apps/{app}/customers":{"get":{"tags":["Customers"],"summary":"List customers","responses":{"200":{"description":"Customer list","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]}},"/apps/{app}/customers/{appUserId}":{"get":{"tags":["Customers"],"summary":"Get a customer subscriber object","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"subscriber":{"$ref":"#/components/schemas/Subscriber"}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"},{"name":"appUserId","in":"path","required":true,"schema":{"type":"string"}}]}},"/apps/{app}/subscriptions":{"get":{"tags":["Subscriptions"],"summary":"List subscriptions","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]}},"/apps/{app}/transactions":{"get":{"tags":["Transactions"],"summary":"List transactions","responses":{"200":{"description":"Transaction list","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]}},"/apps/{app}/events":{"get":{"tags":["Events"],"summary":"List domain events","responses":{"200":{"description":"Event list","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]}},"/apps/{app}/stats":{"get":{"tags":["Apps"],"summary":"App metrics overview","responses":{"200":{"description":"Metrics","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]}},"/apps/{app}/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","responses":{"200":{"description":"Webhook list","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}]},"post":{"tags":["Webhooks"],"summary":"Create a webhook endpoint","responses":{"201":{"description":"Created (secret returned once)","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}},"required":["url"]}}}}}},"/bootstrap":{"post":{"tags":["Bootstrap"],"summary":"Idempotently provision an app with products, entitlements, offerings & packages","responses":{"201":{"description":"Provisioned","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/TenantHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app":{"type":"object"},"entitlements":{"type":"array","items":{"type":"object"}},"products":{"type":"array","items":{"type":"object"}},"offerings":{"type":"array","items":{"type":"object"}}},"required":["app"]}}}}}},"/client/offerings":{"get":{"tags":["Client"],"summary":"Get current offerings (client SDK)","responses":{"200":{"description":"Offerings","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[{"appKey":[]}]}},"/client/subscribers/{appUserId}":{"get":{"tags":["Client"],"summary":"Get subscriber info (client SDK)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"subscriber":{"$ref":"#/components/schemas/Subscriber"}}}}}}},"parameters":[{"name":"appUserId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"appKey":[]}]}},"/client/receipts":{"post":{"tags":["Client"],"summary":"Validate a purchase and refresh the subscriber","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"subscriber":{"$ref":"#/components/schemas/Subscriber"}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"store":{"type":"string","enum":["apple","google"]},"app_user_id":{"type":"string"},"transaction_id":{"type":"string","description":"Apple StoreKit 2 transaction id"},"product_id":{"type":"string","description":"Google product id"},"purchase_token":{"type":"string","description":"Google purchase token"}},"required":["store","app_user_id"]}}}},"security":[{"appKey":[]}]}},"/stores/apple/notifications/{app}":{"post":{"tags":["Stores"],"summary":"Apple App Store Server Notification V2 endpoint","responses":{"200":{"description":"Acknowledged","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"signedPayload":{"type":"string"}},"required":["signedPayload"]}}}},"security":[]}},"/stores/google/notifications/{app}":{"post":{"tags":["Stores"],"summary":"Google Play RTDN (Pub/Sub push) endpoint","responses":{"200":{"description":"Acknowledged","content":{"application/json":{"schema":{"type":"object"}}}}},"parameters":[{"$ref":"#/components/parameters/AppUuid"}],"security":[]}}}}