Authentication

The API authenticates with a bearer token: an API key created by an organisation administrator.

GET /api/v1/card-holders HTTP/1.1
Host: app.cardoffice.nz
Authorization: Bearer idp_AbC123_x9Yz...

Creating a key

1. Sign in as an administrator.
2. Open Settings → Integrations and find API keys.
3. Choose a name that says what the key is for, pick the scopes it needs, and optionally set an expiry in days.
4. Copy the key immediately. It is shown once. CardOffice stores only a hash and cannot show it again.

Keys start with idp_. Treat them like passwords: keep them in a secret store, never in source control or client-side code.

Scopes

A key can do only what its scopes allow. Grant the minimum.

Scope	Allows
card_holders:read	List and read card holders
card_holders:write	Create and update card holders
photos:read	Read the approved-photo change feed
photos:write	Request photo upload URLs and finalise uploads
photos:attest	Mark photos uploaded by this key as staff-captured, so they are approved automatically. Intended for bulk loads from a trusted source
orders:read	List and read orders
orders:write	Create, submit and cancel orders
cards:read	List issued cards and read the card change feed
cards:verify	Reserved for verification clients
scim:provision	SCIM provisioning. Normally the only scope on a SCIM key. See SCIM

A request missing a required scope fails with 403 and the message Missing required scope: <scope>.

Failure behaviour

Every authentication failure returns the same 401 response: a missing header, a malformed key, a wrong secret, a revoked key and an expired key are indistinguishable on purpose, so that a probe learns nothing.

Rotating and revoking

Create the replacement key first, deploy it, then revoke the old one in the same API keys list. A revoked key stops working immediately. Setting an expiry on every key makes rotation routine.

Caution

If a key is exposed, revoke it first and investigate afterwards. Every change made through a key is recorded in the audit log with the key’s identity, so you can see exactly what it did.