API reference
Tokens
The API tokens of your company.
Base URL https://partners.monotree.com/api/v1
· every call needs a token
Endpoints
get/tokens
List API tokens
post
/tokens
Create an API token
delete
/tokens/{token}
Revoke an API token
List API tokens
/tokens
tokens:manage Your company's tokens of the calling token's mode, newest first: a live token lists live tokens, a sandbox token sandbox tokens. A token's value is never shown again; you see its hint.
Parameters
limit
integer · query
default 25 · up to 100
cursor
string · query
next_cursor of the page before, for the next page. Send the same filters with it.
Response · 200 A page of tokens.
object
string
has_more
boolean
next_cursor
string, nullable
cursor for the next page.
data
array of objects
Errors
invalid_cursor: the cursor is not one this API gave out.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
validation_error: a field is missing or invalid; fields says which.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl https://partners.monotree.com/api/v1/tokens \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://partners.monotree.com/api/v1/tokens', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/tokens', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.get(
"https://partners.monotree.com/api/v1/tokens",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json(){
"object": "list",
"has_more": false,
"next_cursor": "string",
"data": [
{
"id": "tok_7",
"object": "token",
"name": "Back office, production",
"abilities": [
"customers:read",
"customers:write",
"webhooks:manage"
],
"sandbox": false,
"hint": "mpt_live_…yQoP",
"token": "string",
"last_used_at": "2026-11-14T08:12:44Z",
"expires_at": null,
"created_at": "2026-11-10T14:00:00Z"
}
]
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Create an API token
/tokens
tokens:manage Creates a token, for example to rotate one without signing in to the portal. The token's value is in this answer only. The new token is of the calling token's mode; a live token may also ask for a sandbox one with sandbox: true. A token can only give abilities it has itself, and a token that expires cannot make one that lasts longer: the new token then needs an expires_at no later than its own. With expires_at the token stops working at that time: calls with it then answer 401 invalid_token. A token made this way is revoked together with the token that made it.
Accepts an optional Idempotency-Key header to make a retry safe.
Request body
name
required
string
API · <name>.
at most 80 characters
abilities
required
array of strings
one of customers:read, customers:write, sellers:write, admins:write, security:read, webhooks:manage, tokens:manage, support:read, support:write, support:configure
sandbox
boolean
false.
expires_at
string, nullable
Response · 201 The token, with its secret value.
id
string
object
string
name
string
abilities
array of strings
one of customers:read, customers:write, sellers:write, admins:write, security:read, webhooks:manage, tokens:manage, support:read, support:write, support:configure
sandbox
boolean
hint
string
token
string
mpt_live_… or mpt_test_…). Only in the answer to Create an API token.
last_used_at
string, nullable
expires_at
string, nullable
created_at
string
Errors
invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks tokens:manage, or asks for an ability it does not have itself. sandbox_only: a sandbox token asked for a live token.
idempotency_in_progress: a call with the same Idempotency-Key is still running.
validation_error: a field is missing or invalid; fields says which. On expires_at also when the calling token expires and the new token has no expires_at, or one later than the calling token's. idempotency_key_reused: the Idempotency-Key was used for a different request.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X POST https://partners.monotree.com/api/v1/tokens \
-H "Authorization: Bearer $MONOTREE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Reporting, read only",
"abilities": [
"customers:read"
],
"expires_at": "2027-11-14T00:00:00Z"
}'$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://partners.monotree.com/api/v1/tokens', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
'json' => [
'name' => 'Reporting, read only',
'abilities' => [
'customers:read',
],
'expires_at' => '2027-11-14T00:00:00Z',
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/tokens', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"name": "Reporting, read only",
"abilities": [
"customers:read"
],
"expires_at": "2027-11-14T00:00:00Z"
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://partners.monotree.com/api/v1/tokens",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
json={
"name": "Reporting, read only",
"abilities": [
"customers:read"
],
"expires_at": "2027-11-14T00:00:00Z"
},
)
data = response.json(){
"id": "tok_7",
"object": "token",
"name": "Back office, production",
"abilities": [
"customers:read",
"customers:write",
"webhooks:manage"
],
"sandbox": false,
"hint": "mpt_live_…yQoP",
"token": "string",
"last_used_at": "2026-11-14T08:12:44Z",
"expires_at": null,
"created_at": "2026-11-10T14:00:00Z"
}
Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.
Revoke an API token
/tokens/{token}
tokens:manage Calls with the token are refused from now on. Every token it created over the API is revoked with it, and every token those created, and so on, whatever their mode. A token may revoke itself, and other tokens of its own mode only: a sandbox token cannot revoke a live one (404).
Parameters
token
required
string · path
tok_…), from List API tokens or Who am I.
Errors
invalid_token: the token is missing, revoked or expired.
insufficient_ability: the token lacks the ability this call needs.
not_found: no such token in the calling token's mode.
rate_limited: too many requests. The general limit is 120 requests a minute for all your tokens of one mode (live or sandbox) together, and 300 a minute per IP address before the token is checked. Some calls have a lower limit of their own, which counts only calls that did what they ask (a call refused with another error uses up no place); the Rate limits guide lists them. Wait for the number of seconds in the Retry-After header.
curl -X DELETE https://partners.monotree.com/api/v1/tokens/tok_7 \
-H "Authorization: Bearer $MONOTREE_TOKEN"$client = new GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://partners.monotree.com/api/v1/tokens/tok_7', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MONOTREE_TOKEN'),
],
]);
$data = json_decode($response->getBody(), true);const response = await fetch('https://partners.monotree.com/api/v1/tokens/tok_7', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.MONOTREE_TOKEN}`,
},
});
const data = await response.json();import os
import requests
response = requests.delete(
"https://partners.monotree.com/api/v1/tokens/tok_7",
headers={
"Authorization": f"Bearer {os.environ['MONOTREE_TOKEN']}",
},
)
data = response.json()Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.