Authentication

The Open API uses API keys (prefixed mono_) to authenticate requests. All requests must include a valid key in the Authorization header and be made over HTTPS. Keys are shown only once when created, so keep them secure and never share them in public repositories or client-side code.

curl https://customer.monotree.com/api/open/v1/walls \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Accept: application/json"

A missing, unknown, revoked or expired key returns 401; see Errors. Only admins can create, revoke and delete tokens in the CMS.

Scopes

Each token has scoped permissions — for example, read:posts allows reading posts while write:posts allows creating, updating, and deleting them. A write scope does not include the matching read scope: give the token both if it needs both. A request that requires a scope you don't have returns 403 Forbidden with the message This token does not have the required scope: <scope>.

read:todolists also exists. It has no HTTP endpoint and is only used by the MCP server.

GET /token and POST /feedback need no scope.

Checking a token

GET /token describes the token you call it with: its name, its scopes and when it expires. It works with any valid token and needs no scope, so use it to check a token at setup instead of waiting for the first 403.

curl https://customer.monotree.com/api/open/v1/token \
  -H "Authorization: Bearer mono_your_token_here"

{
  "data": {
    "name": "Rewards integration",
    "scopes": ["read:achievements", "read:users"],
    "expires_at": null
  }
}

expires_at is null for a token that never expires. A revoked or expired token gets 401, like on every other endpoint. The token's IP restriction is not returned.

Authorship

When creating a token, you choose who content is attributed to. Select Myself to have posts and announcements appear under your name, or System user to attribute them to the platform. This cannot be changed after the token is created. If the admin who created a Myself token is deleted, content is attributed to the system user from then on.

IP restrictions

You can optionally restrict a token to one IPv4 or IPv6 address (no ranges or lists). If set, requests from any other IP are rejected with 403 and the message Request IP is not allowed for this token. Useful for server-to-server integrations with a static egress IP.

Expiration

Tokens may have an expiration date, which must be in the future when the token is created. Expired tokens return 401 Unauthorized. Admins can also revoke or delete a token in the CMS; it then returns 401 as well.

Webhooks made with a token stop with it. Revoking or deleting a token revokes the incoming and outgoing webhooks it created. While a token is expired, its outgoing webhooks receive no deliveries and its incoming webhooks answer 403. Webhooks created in the CMS, and outgoing webhooks that already existed before v0.59.0, do not depend on a token.

Feature-gated endpoints

Some endpoints belong to features that are switched on per company. If the feature is off, those endpoints return 403 with the message The <feature> feature is not enabled. even with the right scope, for reads and writes alike. Ask your Monotree contact to enable it.

Only the articles of handbook and course chapters are gated. Posts have no article, and the articles of announcements, events, calendar entries, staff cards, certificates and achievements are not gated by any feature.