Authentication and keys: Subscriptions docs

Every request carries a workspace API key: its key id in the X-Chargezen-Key-Id header and its secret as a bearer token in Authorization.

Create a key

Open API keys

In Chargezen, go to Settings → API keys and add a key.

Choose what it can do

Under What it can do, turn on what your server needs (see the table below).

Copy the secret

The secret is shown once, when the key is created. Store it with your server's other secrets.

In Chargezen	Key permission	Allows
Read customers, products and subscriptions	`workspace:read`	Every GET
Change subscriptions	`subscriptions:write`	Every POST under a subscription, including order now
Create subscriptions	`subscriptions:create`	`POST /customers/{customer_id}/subscriptions`

A key acts as you

A key that reads or changes subscriptions acts as the teammate who gave it that access, with that teammate's current role. Each request also needs the matching permission in that role:

Finding customers: managing customers, viewing subscriptions or viewing CheckoutOS.
Listing and reading subscriptions, listing plans and checking a new subscription: viewing subscriptions.
Upcoming orders, swap options, every change, order now and creating: managing subscriptions.

If you remove the teammate from the workspace or take away the permission, the key stops working for those requests and answers PERMISSION_REQUIRED.

Send the key

Every request

curl "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET"

Idempotency-Key on every POST

Every POST needs an Idempotency-Key header: any unique string, and a UUID is best. To retry a request, send it again with the same key.

Create, cancel, order now and payment-method requests are tied to that key, so they never happen twice.
The other changes set a target state (paused, a quantity, an address), so repeating them is harmless.

Retry with the same key

KEY=$(uuidgen)
curl -X POST "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/cancel" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET" \
  -H "Idempotency-Key: $KEY"
# The connection dropped? Send the same request with the same $KEY.

Keep the secret on your server

The key acts as a teammate. Never put it in a storefront, an app bundle or anything a shopper can read.

When a key is refused

Status	Code	What happened
401	`API_KEY_REQUIRED`	The key id or the bearer secret is missing.
401	`API_KEY_INVALID`	The key id and secret don't match an active key.
403	`API_KEY_SCOPE_REQUIRED`	The key isn't allowed to do this. The message names the permission it needs.
403	`PERMISSION_REQUIRED`	The teammate the key acts for lost access to the workspace, or their role lacks the permission.
422	`IDEMPOTENCY_KEY_REQUIRED`	A POST came without an Idempotency-Key header.

Authentication and keys