REST API
Keys and roles
How an organization admin makes an API key, what Read, Start and Full keys may do, and how to roll or revoke a key without breaking your integration.
An API key lets one system act as your organization. Each key is its own integration, with a name and a role, and it shows up by that name wherever it acts: "Booking system started Room 12", "Weekly report" in nobody's activity because it only reads.
Making a key
Only an organization admin can make, roll or revoke keys. In the app, open Profile, Integrations, New API key, then:
- Name it after the system that will use it. The name is what your team sees in the activity.
- Choose its role.
- Choose when it expires: never, in 90 days or in a year.
The key appears once, with a Copy button. After that the app shows only its start and its last four characters, such as csq_Zk3mQ8vL2pR9…9f3k, so you can tell keys apart. An organization can have 20 integrations.
Sending the key
Send it in the Authorization header of every request:
curl https://api.checklistsquad.com/api/me -H "Authorization: Bearer csq_…"
A key is csq_, the integration's twelve-character id, then a 64-character secret. There is no token to exchange first and nothing to refresh.
Roles
A role decides what the key may do anywhere in the organization. It never reaches members, squads, settings or other keys, whatever the role.
| Read | Start | Full | |
|---|---|---|---|
| See templates, checklists, steps, assignments, activity, people and squads | yes | yes | yes |
| Start a checklist | yes | yes | |
| Assign, tick, answer, edit and finish the checklists it started | yes | yes | |
| Assign, tick, answer, edit and finish any checklist | yes | ||
| Add or edit templates in the library | yes | ||
| Invite people, form squads, change settings, manage keys |
When a key starts a checklist, the key's integration owns it, and so does the admin who made the key. That admin can rename it, reassign it or finish it in the app like any checklist of their own.
A key can never be assigned work, and it is not part of "Everyone in" your organization.
Rolling a key
Roll a key when you want to replace it without downtime, or when you think it was exposed. Open the integration and choose Roll key, then how long the old key keeps working: an hour, a day or a week. The new key works at once and is shown once. Put it in your system, and the old one stops by itself when the time is up.
Revoking a key
Revoke integration stops the key at once: its next request answers 401. Nothing undoes it; make a new key instead. The checklists and templates it made stay, owned by the admin who made the key.
Keeping a key safe
- Keep it in your system's secret store, not in source code, a spreadsheet or a chat.
- Give each system its own key, so you can revoke one without touching the others.
- Use the smallest role that does the job. A report needs Read.
- A leaked key reaches what its role reaches in one organization, and nothing beyond it. Roll it, or revoke it, as soon as you know.