API keys and scopes

An API key (an OAuth client) is how your systems sign in to the API. Keys live under Company Settings → Integrations → API Keys, which only an Owner or Admin can open.

Creating a key

1. Choose New API Key, give it a name that says what uses it (for example “Provisioning system”), and tick the scopes it may use.
2. Confirm with your password.
3. Copy the Client ID and Client Secret. The secret is shown once and can’t be shown again. If you lose it, rotate the key.

Give each system its own key with only the scopes it needs. A leak then reaches less, and you can revoke one system without stopping the others.

Scopes

A scope is permission for one kind of call. Each endpoint in the reference lists the scope it needs. Scopes follow the pattern area:action:

Area	What it covers
account	Your account’s details and resources
billing	Invoices, credit notes, balance and pricing
data	NBN and Opticomm services and orders
voice	Numbers, SIP trunks and call records
sms	Sending SMS and reading history
tickets	Support tickets
webhooks	Webhook endpoints and deliveries
watch	Email watches

The actions are read, create, update and delete (send for SMS). API scopes lists every scope a key can be granted.

• account:update and account:delete can change your account itself, so only an Owner can grant them.
• A token carries only the scopes you ask for and the key is allowed. Any others are dropped without an error, so check the scope field of the token response when a call answers 403.

Changing a key

Edit changes a key’s name or its scopes. Changing scopes asks for your password, as creating a key does, and is recorded in your account’s audit trail. A token that still carries a scope you removed stops working at once, and your system must request a new token (which it does anyway every hour). Adding a scope leaves current tokens working; request a new one to use it.

Rotating and revoking

• Rotate issues a new secret and keeps the key’s ID and scopes. Tokens issued with the old secret stop working. Rotate when a secret may have leaked, or when someone who had it leaves.
• Revoke turns the key off for good. Its tokens stop working at once. Use it when a system is retired, or straight away if you suspect a compromise; it needs no password, so nothing slows it down.