Authentication

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 key is the prefix saasybill_live_ followed by 43 random characters.

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.

Open Developer Settings

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

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.

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
`invoices:read`	Read Invoices	List and retrieve invoices
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.

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_ exist in the format but can’t be created yet. If one authenticates, the API refuses it with 403 sandbox_not_available, so nothing runs against live data by accident. To test an integration, use a second organisation connected to a Xero Demo Company. See Testing.

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`	`sandbox_not_available`	A `saasybill_test_` key was used.

See Errors for the full list.

Getting started

Fundamentals

Integration guides

Webhooks

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

API keys

Create an API key

Revoke an API key

Key status

Scopes

Test keys

Authentication errors

​API keys

​Create an API key

​Revoke an API key

​Key status

​Scopes

​Test keys

​Authentication errors

API keys

Create an API key

Revoke an API key

Key status

Scopes

Test keys

Authentication errors