Entitlements

Entitlements are populated server-side (your server-side grant, or an optional subscription integration) — this read endpoint is the only client-side way to inspect them. It never writes, so a client cannot grant itself access.

is_active is derived: an entitlement reads active only when it is marked active and has not passed its expiration_date. A lapsed subscription therefore never reads as active, even before its expiry event is processed.

Endpoints

Method	Path	Description
GET	`/client/entitlements`	The current user's entitlements.
POST	`/client/entitlements/restore`	Restore Purchases — re-sync owned entitlements.

GET /client/entitlements

Query parameters

Param	Type	Description
`active_only`	boolean	When `true`, returns only currently-active (unexpired) grants.

Response 200

{
  "data": [
    {
      "entitlement_id": "pro",
      "is_active": true,
      "product_id": "com.example.pro_annual",
      "store": "app_store",
      "purchase_date": "…",
      "expiration_date": "…",
      "period_type": "normal"
    }
  ]
}

Errors

500 FETCH_FAILED.

Try it:

GET/client/entitlements

client auth

curl -X GET 'https://api.amba.dev/v1/client/entitlements'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/client/entitlements' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

POST /client/entitlements/restore

Re-syncs the user's owned entitlements from the configured subscription service and re-applies them, returning the active set. This is the App Store "Restore Purchases" requirement (guideline 3.1.1). No request body.

Fail-closed: if the subscription service is unreachable, the endpoint returns an error and the user's entitlement state is left unchanged — it never silently unlocks or revokes.

Response 200

{
  "data": {
    "restored_count": 1,
    "entitlements": [
      { "entitlement_id": "pro", "is_active": true, "product_id": "…", "store": "app_store" }
    ]
  }
}

Errors

404 USER_NOT_FOUND — no app user resolved from the session token.
409 RESTORE_UNAVAILABLE — no subscription service configured for the project.
502 RESTORE_UPSTREAM_FAILED — the subscription service could not be reached; access unchanged.
500 RESTORE_FAILED.

Curl:

curl -X POST '${BASE_URL}/client/entitlements/restore' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

On this page