API
Authentication
API keys. Where to make one, who it acts as, the level it has and the leads switch.
The API signs a call in by an API key.
Make a key
Section titled “Make a key”- Sign in to Signalbox at app.trysignalbox.com.
- Open API keys. Only a workspace admin can make a key.
- Make a key, and choose its level and whether it may read leads.
- Copy the key then. The full key is shown once. Signalbox stores only a hash of it and a short hint, so nobody can show it to you again.
Send the key
Section titled “Send the key”Send it in the x-api-key header:
curl https://api.trysignalbox.com/api/v1/me \ -H "x-api-key: YOUR_API_KEY"The API also accepts Authorization: ApiKey YOUR_API_KEY.
Who a key acts as
Section titled “Who a key acts as”- A key acts as the person who made it, in the workspace it was made in.
- The workspace comes from the key. It is never read from the address or the query string.
- A key stops working when that person leaves the workspace or their account is deactivated.
- A key never acts as root. Root is the platform’s own role. The most a key can be is an admin of its workspace.
A key’s level
Section titled “A key’s level”Each key has a level. It is never higher than its maker’s role.
| Level | The key may |
|---|---|
| Read | Read flows, queues, meeting types and settings. Change nothing. |
| Build | Also write draft flows, queues and meeting types, and dry run a draft. |
| Publish | Also publish, pause and delete flows, and change what a live visitor gets: form routing, sites, working hours and settings. |
Give a key the lowest level that does its job.
The level is set when the key is made and cannot be changed after. To change it, make a new key and delete the old one.
A key made before keys had levels shows as “As its creator”. It acts with its maker’s role and cannot read leads.
A call the level does not allow is answered 403, with a sentence that names the level it needs.
The leads switch
Section titled “The leads switch”Reading leads is a separate switch on the key, off by default. Leads hold personal data. Turn it on only for a key that needs to read them.
Every change made with a key is written to the workspace’s audit, and names the key.
The same levels and the same switch apply to an AI agent. See Levels and leads.
Keep a key safe
Section titled “Keep a key safe”- Keep it out of source control, web pages and anything you share.
- Use a key for one purpose, so you can delete it without breaking something else.
- Delete a key on the API keys page as soon as it is not needed, or if it may have been seen.
An API key is not the site key in the Signalbox tag. The site key is public and only says which workspace a page belongs to. An API key is secret and never goes in a page.