Get started
Authentication
Every call carries an API token. Tokens belong to your company, can do only what they were given, and are either live or sandbox.
Sending the token
Send the token as a bearer token on every call:
GET /api/v1/customers HTTP/1.1
Host: partners.monotree.com
Authorization: Bearer mpt_live_9fK2…
Accept: application/jsonA call without a token, or with a revoked or expired one, gets 401 with the type invalid_token. Send request bodies as JSON with Content-Type: application/json.
Live and sandbox tokens
| Starts with | Mode | What it reaches |
|---|---|---|
mpt_live_ |
Live | Your real customers. A new customer is set up on Monotree for real. |
mpt_test_ |
Sandbox | Test customers only, kept apart from live ones. Nothing is set up for real. See Sandbox and testing. |
The URL is the same for both; the token decides. A sandbox token never sees a live customer and the other way round, so IDs from one mode give 404 in the other.
Abilities
An ability is one thing a token may do. A token has only the abilities it was given when it was made:
| Ability | Lets the token |
|---|---|
customers:read |
Read customers, company IDs, events, statistics, adoption alerts, sellers and the monthly statement |
customers:write |
Create, change, submit, retry, suspend, resume and cancel customers, and resend admin invitations |
sellers:write |
Add, change and disable sellers, and invite new ones to the portal. Mind what that means: a seller this token adds or invites signs in to the portal and sees the customers they sign from then on. What a seller already has is not this ability's to hand over (see admins:write) |
admins:write |
Together with sellers:write: make someone an admin, and change, invite, disable or reset an admin; change the email address of anyone who signs in, is invited or has customers, or reset their two-factor sign-in; invite, for the first time, a seller who already has customers; and change the external_ref of a seller who has customers, signs in or is invited |
security:read |
Read how your people sign in: two-factor sign-in, passkeys and the sign-in log |
webhooks:manage |
Add, change, test, pause and delete webhook endpoints, rotate their signing secrets, and list and redeliver deliveries. It reads no events by itself: a token only sees and touches an endpoint when it may read every event that endpoint gets and has got. Any other endpoint answers 404, as if it were not there |
tokens:manage |
List and revoke the API tokens of the token's own mode, and create new ones: of its own mode, or a sandbox token from a live one (never the other way round) |
support:read |
Read support threads, their messages, drafts, escalations, tags and the desk's numbers |
support:write |
Start, answer, assign, close, merge and escalate support threads, add notes and use the assistant's drafts |
support:configure |
Change the support desk's settings and presence, manage what its assistant has been taught, and delete threads |
Who am I needs no ability. Each endpoint in the reference shows the one it needs.
A call the token may not make gets 403 with the type insufficient_ability, and the message names the ability it needs. Give each integration only what it uses: a reporting job needs customers:read alone.
Getting a token
- In the portal: an admin opens Developers › API tokens › Create token.
- Without the portal: if nobody at your company uses the portal, ask your Monotree contact for your first token.
- Over the API: a token with
tokens:managecan create more with Create an API token. The new token can have only abilities the calling token has itself. It is of the calling token's mode; a live token can also create a sandbox token, never the other way round. If the calling token expires, the new one must have anexpires_attoo, no later than the calling token's (422otherwise). A token made by a token is revoked together with the token that made it.
A token lists and revokes tokens of its own mode only: a sandbox token never reaches a live one.
Expiry
A token works until it is revoked, unless you give it an end: pick Expires when you create it in the portal (30 days, 90 days or 1 year), or send expires_at to POST /tokens. expires_at must lie in the future. From that moment calls with the token get 401 invalid_token, and the portal's list shows it as Expired. An expired token is not deleted by itself; revoke it to tidy up.
A token is shown once, when it is made. Monotree keeps only a hash of it; if it is lost, make a new one.
Rotating a token
To replace a token without downtime:
- Create the new token (portal or
POST /tokens). - Deploy it to your systems.
- Check it works with
GET /partner. - Revoke the old one (portal or
DELETE /tokens/{id}).
Tokens belong to your company, not to a person, so an integration keeps working when someone who made it leaves.
Keeping tokens safe
- Keep tokens on your servers, in a secrets manager or environment variables. Never put one in a mobile app, a browser or a repository.
- Use a sandbox token for development and CI.
- Revoke a token you think has leaked; nothing else is needed.
- Give each system its own token with a name that says what it is, only the abilities it uses, and an expiry date. The timeline of a customer and the
actorof an event showAPI · <token name>for what a token did. - List API tokens shows when each token was last used (
last_used_at): revoke the ones nobody uses.