API reference

Tokens

The API tokens of your company.

Base URL https://partners.monotree.com/api/v1 · every call needs a token

List API tokens

get /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

How many to return in a page, 1 to 100.

default 25 · up to 100

cursor

string · query

The 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

Whether there is a page after this one.

next_cursor

string, nullable

Pass as cursor for the next page.

data

array of objects

Errors

400 invalid_cursor: the cursor is not one this API gave out.
401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
422 validation_error: a field is missing or invalid; fields says which.
429 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"
200 · Response
{
    "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.

Sending…

                    

Create an API token

post /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

A name for your own use. It shows on timelines as API · <name>.

at most 80 characters

abilities required

array of strings

What the token may do: only abilities the calling token has itself.

one of customers:read, customers:write, sellers:write, admins:write, security:read, webhooks:manage, tokens:manage, support:read, support:write, support:configure

sandbox

boolean

Defaults to the mode of the calling token. A sandbox token cannot ask for false.

expires_at

string, nullable

When the token stops working; a time in the future and before 2038. Left out or null: never.
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

The start and the last four characters of the token, to tell tokens apart.

token

string

The token itself (mpt_live_… or mpt_test_…). Only in the answer to Create an API token.

last_used_at

string, nullable

expires_at

string, nullable

When the token stops working; null for never.

created_at

string

Errors

400 invalid_idempotency_key: the Idempotency-Key is longer than 255 characters.
401 invalid_token: the token is missing, revoked or expired.
403 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.
409 idempotency_in_progress: a call with the same Idempotency-Key is still running.
422 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.
429 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"
}'
201 · Response
{
    "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.

Sending…

                    

Revoke an API token

delete /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

The token's ID (tok_…), from List API tokens or Who am I.

Errors

401 invalid_token: the token is missing, revoked or expired.
403 insufficient_ability: the token lacks the ability this call needs.
404 not_found: no such token in the calling token's mode.
429 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"

Only mpt_test_… tokens work here; nothing reaches a real customer. Kept in this browser tab only.

Sending…