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 "Content-Type: application/json"

Scopes

Each token has scoped permissions — for example, read:posts allows reading posts while write:posts allows creating, updating, and deleting them. A request that requires a scope you don't have returns 403 Forbidden.

Scope	Capability
`read:posts`, `write:posts`	Read or create/update/delete posts
`read:comments`, `write:comments`	Read or create/update/delete comments
`write:media`	Upload media files
`read:announcements`, `write:announcements`	Read or create/update/delete announcements
`read:handbooks`, `write:handbooks`	Read or create/update/delete handbooks and chapters
`read:courses`, `write:courses`	Read or create/update/delete courses and chapters
`read:journeys`	List journeys and read per-user journey status
`read:achievements`, `write:achievements`	List achievements, their awards and the awards a user holds, or create, update and award achievements
`read:articles`, `write:articles`	Read or write article content (elements)
`read:events`, `write:events`	Read or create/update/delete events
`read:calendar_entries`, `write:calendar_entries`	Read or create/update/delete calendar entries
`read:calendar_event_types`, `write:calendar_event_types`	Read or create/update calendar event types
`read:locales`	List the platform's active languages
`read:users`, `write:users`	List users, or create/delete users and set profile pictures
`read:groups`, `write:groups`	List groups, or create groups
`read:org_chart`	Read the organizational chart
`read:walls`	List walls
`read:stats`	Read aggregated statistics
`read:managerhub`	Read Manager Hub team and progress reports
`read:surveys`	Read surveys and answers
`read:forms`	List and read forms (whistleblower forms excluded)
`read:formresponses`	Read form responses incl. public comments and internal notes
`read:certificates`, `write:certificates`	Read or create/update/delete certificates and assign them
`read:certificatetypes`, `write:certificatetypes`	Read or create/update/delete certificate types
`read:staff_cards`, `write:staff_cards`	Read or create/update/delete staff cards
`read:webhooks`, `write:webhooks`	Read or create/update/revoke outgoing webhook endpoints
`read:incoming_webhooks`, `write:incoming_webhooks`	Read or create/update/revoke incoming webhooks
`read:bots`, `write:bots`	Read or create/update bot users
`write:chat_messages`	Send a direct message to a user as a bot, and pin bot messages
`write:notifications`	Send notifications to the activity feed of groups and users

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

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.

GET

/api/open/v1/token

The calling token's name, scopes and expiry

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.

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.

IP restrictions

You can optionally restrict a token to one IP address (no ranges or lists). If set, requests from any other IP are rejected with 403. Useful for server-to-server integrations with a static egress IP.

Expiration

Tokens may have an expiration date. Expired tokens return 401 Unauthorized.

Feature-gated endpoints

Some endpoints belong to features that are switched on per company: Org Chart, Manager Hub and Achievements. If the feature is off, those endpoints return 403 with the message The <feature> feature is not enabled. even with the right scope. Ask your Monotree contact to enable it.