API tokens and scopes
Create, restrict, expire and revoke workspace API tokens.
Create and test a token
- Select the intended workspace and open API & Agents.
- Create a token with a descriptive integration name.
- Choose only the scopes the integration needs.
- Choose all bots or a specific bot allowlist. Bot-restricted tokens cannot create new bots.
- Choose an expiry of 30, 90 or 365 days, or no expiry.
- Copy the token when it is shown and store it in your backend/client secret environment.
- Call a permitted read operation to confirm access before enabling writes.
curl "https://api.dev-moncha.com/v1/bots" \ -H "Authorization: Bearer $MONCHA_API_TOKEN"
Scope reference
The standard preset includes the day-to-day scopes and excludes bots:write. The full preset includes all ten. Review write scopes before allowing an agent to act.
| Scope | Allows |
|---|---|
| bots:read | List accessible bots. |
| bots:write | Create a bot within eligible workspace/tier capacity; requires an all-bots token. |
| kb:read | List knowledge documents. |
| kb:write | Queue URL/text knowledge ingestion. |
| chat:invoke | Ask a bot; normal usage rules apply. |
| conversations:read | Read conversation lists and transcripts. |
| leads:read | Read leads. |
| analytics:read | Read aggregate 30-day analytics. |
| bookings:read | Read booking lists and details. |
| bookings:write | Confirm, reject, reschedule or cancel eligible bookings. |
Restrictions, expiry and rotation
- Pass an allowed chatbotId when a bot-restricted token calls knowledge, chat, leads or analytics.
- A valid token cannot bypass the current plan, payment state or bot allowlist.
- The complete secret is shown only when created. If it is lost, create a replacement.
- Rotate by creating a new token, updating the consuming application, testing it and revoking the old token.
- Revocation or expiry causes authentication failure. Restoring paid/live service can restore an otherwise valid token without replacing it.
- Keep tokens out of browser bundles, source control, screenshots and support messages.