PayKitBeta

Entitlements

Two ways to check what a customer's active subscriptions grant. Entitlements merge across a customer's access-granting subscriptions (boolean OR, limit MAX).

GET/v1/clients/{clientId}/projects/{projectId}/customers/{externalRef}/entitlements

Read entitlements

customers.read

Direct read: one call per feature gate check.

Path parameters

clientIdstringYour PayKit client id.
projectIdstringThe project.
externalRefstringYour id for the user.

Add-on grants are already folded in: a boolean entitlement is true-wins, and a limit entitlement is added on top of the plan limit and multiplied by the quantity bought.

Every grant reads the add-on version it was sold against, so publishing a new version never changes what an existing grant gives. A renewing grant is the exception: it follows the current version at each renewal.

curl -X GET "https://api.paykit.co.za/v1/clients/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/projects/f6e5d4c3b2a1908172635445362718a9/customers/user_123/entitlements" \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK
{
  "entitlements": [
    {
      "featureCode": "seats",
      "kind": "limit",
      "boolValue": null,
      "limitValue": "15"
    }
  ],
  "subscriptions": [
    {
      "state": "active",
      "currentPeriodEnd": "2026-08-13T10:00:00Z",
      "planVersionId": "pv_9a8b…"
    }
  ],
  "addons": [
    {
      "code": "game-zelda",
      "expiresAt": null
    }
  ],
  "balances": {
    "support-credits": "7"
  }
}
POST/v1/clients/{clientId}/projects/{projectId}/customers/{externalRef}/entitlement-tokens

Mint an entitlement token

customers.read

Signed token you cache and verify locally against the public JWKS, with no per-check call. See the Entitlement tokens guide for the verification recipe.

Path parameters

clientIdstringYour PayKit client id.
projectIdstringThe project.
externalRefstringYour id for the user.

Request body

ttlSecondsintegerToken lifetime in seconds (e.g. 300).
curl -X POST "https://api.paykit.co.za/v1/clients/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/projects/f6e5d4c3b2a1908172635445362718a9/customers/user_123/entitlement-tokens" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ttlSeconds":300}'
200 OK
{
  "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6…",
  "alg": "ES256",
  "kid": "k_2026a",
  "expiresAt": "2026-07-13T10:05:00Z",
  "entitlements": [
    {
      "featureCode": "seats",
      "kind": "limit",
      "limitValue": 10
    }
  ]
}
GET/.well-known/jwks.json

Public JWKS

no auth

Public keys for verifying entitlement tokens. No auth.

curl -X GET "https://api.paykit.co.za/.well-known/jwks.json"
200 OK
{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "kid": "k_2026a",
      "x": "…",
      "y": "…",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}
InvoicesUsage