API keys and scopes

An API key is how your own system proves it’s allowed to act on your organisation’s behalf — and scopes decide exactly what it’s allowed to do with that permission.

What it is

Each key carries one or more scopes, chosen when it’s minted: surveys:read, properties:read, properties:write, properties:archive, tenancies:read, tenancies:write, work-orders:read, work-orders:write, contractors:read, contractors:write. Only a SHA-256 hash of the key is stored server-side — the plaintext is shown once, at the moment you mint it, and never again. properties:archive is deliberately separate from properties:write, so a key trusted to create and edit stock data isn’t automatically trusted to remove a property from the active register. tenancies:write covers create, edit and delete in one scope, because tenancy data is ordinary operational data, not sealed evidence.

Before you start

Minting or revoking a key needs organisation-admin access to Settings, a level higher than most other Settings sections, and the Platform plan.

How to do it

1. Open Settings → API & webhooks.
2. Enter a label so you can identify the key later, tick the scopes it needs, and click Mint key.
3. Copy the plaintext key immediately — it’s shown once and can’t be retrieved again.
4. Store it as a secret in your own system, never in source control or a shared document.
5. To retire a key, click Revoke next to it and confirm — any integration using it stops working immediately, with no grace period.

How it integrates

A key can only ever use the scopes it was granted at minting time, independent of how much access your own organisation-level role has — a key scoped to surveys:read alone can never write a work order, whatever an org-admin could otherwise do through the portal. Every call made with a key is written to your organisation’s audit log, and tenancies:* scopes are independent of properties:*, so a key can be scoped to tenancy contact details without also granting property stock access, or the other way round.

Common problems

• I lost the plaintext key shown after minting. It can’t be retrieved again — revoke it and mint a replacement.
• A call fails with “missing scope”. The key wasn’t minted with the scope that specific endpoint needs. Mint a new key with the right scopes rather than trying to add one to an existing key.
• We need to change what a key can do. Scopes are fixed at minting time — revoke the old key and mint a new one with the scopes you actually need.
• The whole section shows an upgrade notice instead of the controls. API keys are a Platform-plan feature.