---
title: "Authentication and keys: Subscriptions docs | Chargezen"
description: "Create a workspace API key, choose what it can do, and send its key id, secret and an Idempotency-Key with Subscriptions REST API requests."
url: "https://chargezen.com/docs/subscriptions/api/authentication"
lang: "en"
updated: "2026-11-09"
---

Canonical URL: https://chargezen.com/docs/subscriptions/api/authentication

# Authentication and keys

Create a workspace API key, choose what it can do, and send its key id, secret and an Idempotency-Key with Subscriptions REST API requests.

Last updated: 2026-11-09

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

1

#### Open API keys

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

2

#### Choose what it can do

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

3

#### 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

```bash
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

```bash
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. |

### Related Articles

[

#### Subscriptions REST API

What the API covers and a quick start



](https://chargezen.com/docs/subscriptions/api)[

#### Errors and retries

Refused keys and missing permissions



](https://chargezen.com/docs/subscriptions/api/errors)

Was this page helpful?

Need more help? [Contact support](https://chargezen.com/docs/checkoutos/troubleshooting/support)