Authentication & keys

Every API call is authenticated with a key, sent in the x-api-key header. The base URL is https://api.qbill.dev/v1.

The key in the header

curl https://api.qbill.dev/v1/customers \
  -H "x-api-key: qb_test_sk_…"

With the Node SDK, pass the key to the constructor: new QBill("qb_test_sk_…"). The @qbill/node package arrives on npm soon; until then, curl works today.

Three kinds of keys

Prefix App What it can do
qb_test_sk_… sandbox The whole API, never reaching Wave (see Test mode).
qb_live_sk_… live The whole API, with real payments.
qb_publishable_sk_… live or sandbox Four read routes: GET /v1/plans, GET /v1/plans/:id, GET /v1/plans/:id/tiers and GET /v1/plans/:id/price-components.

A publishable key that calls any other route gets a 403 publishable_key_forbidden error. It cannot create customers, invoice or refund.

Read-only

A key can be created with the read_only scope. It accepts reads and refuses every write with a 403 api_key_read_only error.

One key = one app

A key carries its app: there is no X-App-Id header to send. A live key can only be created on the live app and a test key only on the sandbox; creating one on the wrong side is refused with a 400 key_mode_mismatch error. A publishable key can be created on either.

Rotation

Create, replace or revoke your keys in the developer portal, under API Keys. Two rules:

  • the SDK refuses a publishable key: it is only for reading plans;
  • never put a secret key (qb_test_sk_…, qb_live_sk_…) in a browser or a mobile app: keep it on the server.

The error format is described in Errors.

← QuickstartTest mode →