Authentication

Authenticate with API keys, and limit each key to the scopes it needs

The API uses bearer API keys. Each key belongs to one organisation and carries a set of scopes that decide what it can do.

Authorization: Bearer saasybill_live_…

A request without a valid key answers 401. A request whose key lacks the scope for the endpoint answers 403.

---

API keys

A live key is the prefix saasybill_live_ followed by 43 random characters. A test key uses saasybill_test_ instead.

saasybill_live_x3F9k2Lm8QpR4vTn7YbZ1cWdAe5GhJuI6oXsN0MqPyK

The prefix tells a person, and a secret scanner, what the string is. If a key ends up in a public repository, the scanner can find it.

Treat a key like a password. It can create subscriptions and read customer data. Never put it in browser code, a mobile app or a repository. Keep it on your server, in an environment variable or a secrets manager.

Create an API key

Only an owner or admin can create, view or revoke keys.

1. Open Developer Settings

   Go to Organisation Settings, then Developer Settings, then API Keys.

2. Create the key

   Click Create API Key and fill in the fields.

   Field	Description
   Name	A label for you. Up to 100 characters. Use the name of the integration, such as Signup integration.
   Permissions	The scopes the key holds. Choose only what the integration needs.
   Expires	Never, in 30 days, in 90 days, or in 1 year.

3. Copy the key

   Click Create Key, then copy the key from the Your New API Key dialog. It cannot be shown again. If you lose it, create a new key and revoke the old one.

An organisation can have up to 25 active keys. The list shows each key’s name, its first few characters, its scopes, when it was last used, and when it expires.

Revoke an API key

Open the key’s menu and click Revoke Key. Anything using the key stops working straight away, and this can’t be undone.

Key status

Status	Meaning	API answer
Active	The key works.
Revoked	Someone revoked it.	401 api_key_revoked
Expired	It passed its expiry date.	401 api_key_expired

---

Scopes

A scope grants access to one part of the API. An endpoint names the one scope it needs.

Scope	Label in the app	Allows
customers:read	Read Customers	List and retrieve customers
customers:write	Create Customers	Create customers, and Xero contacts where the organisation allows it
catalogue:read	Read Plans And Charges	List and retrieve plans and charges
subscriptions:read	Read Subscriptions	List and retrieve subscriptions
subscriptions:write	Manage Subscriptions	Create subscriptions, change units, end and restore them
usage:write	Report Usage	Report usage events, which are billed to the subscription they name
invoices:read	Read Invoices	List and retrieve invoices
credit_notes:read	Read Credit Notes	List and retrieve credit notes, and see where their credit was applied
None needed		Retrieve the organisation

A write scope does not include its read scope. A key that creates subscriptions and also needs to read them holds both subscriptions:write and subscriptions:read.

Give each integration its own key with the fewest scopes it needs. A signup integration usually needs catalogue:read, customers:read and subscriptions:write. A reporting integration needs only read scopes. A service that meters usage and reports it needs usage:write alone, so a leaked usage key can’t create or end subscriptions.

When a key lacks a scope, the error names it.

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the `subscriptions:write` scope.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

---

Test keys

Keys with the prefix saasybill_test_ are test keys. You create them inside a sandbox, in the sandbox’s own Developer Settings, in the same way as a live key.

A test key works only in its sandbox, and a live key works only in a live organisation. Using one in the wrong place answers 403 api_key_mode_mismatch, so nothing runs against live data by accident.

Keep test and live keys in separate environment variables, so a deployment can’t mix them up.

---

Authentication errors

Status	Code	Cause
401	invalid_api_key	The header is missing or malformed, or the key doesn’t exist.
401	api_key_revoked	The key has been revoked.
401	api_key_expired	The key has expired.
403	insufficient_scope	The key lacks the scope the endpoint needs.
403	api_key_mode_mismatch	A test key was used outside its sandbox, or a live key was used inside one.

See Errors for the full list.