Developers · API 1.0.0

Mentornity API and webhooks

Read your programme's members, matches and meetings over a REST API, and get a signed webhook the moment they change. Included in paid plans.

Base URL

https://api.mentornity.com/v1

Format

JSON, UTF-8, snake_case

Auth

Bearer API key, one per programme

Spec

openapi.json

Quickstart

1. In the admin panel, open Settings, then the API & Webhooks tab. If API access is not yet enabled for your programme, the tab has a button to ask us.
2. Create a key, pick the permissions it needs, and copy it. It is shown once.
3. Call the API from your server:

curl https://api.mentornity.com/v1/members?limit=2 \
  -H "Authorization: Bearer mtk_live_..."

{
  "object": "list",
  "data": [
    {
      "object": "member",
      "id": "6650f1c2a7...",
      "user": { "object": "person", "id": "64a1...", "name": "Ada Lovelace", "email": "ada@example.com" },
      "role": "mentee",
      "status": "active",
      "joined_at": "2026-09-01T08:30:00Z",
      "left_at": null,
      "updated_at": "2026-10-02T11:04:12Z"
    }
  ],
  "has_more": true,
  "next_cursor": "NjY1MGYxYzJhNy4uLg"
}

Authentication

Send the key in the Authorization header as Bearer <key>. Keys look like mtk_live_ or mtk_test_ followed by 32 letters and digits. We store only a hash of each key, so a lost key cannot be shown again: revoke it and create a new one.

A key belongs to exactly one programme and can read nothing outside it. Each key has permissions (scopes); a request outside them returns 403 insufficient_scope.

Keep keys on your server. The API sends no CORS headers, so a browser page cannot call it, and a key in a web or mobile app would be readable by anyone. Revoking a key takes effect within a minute.

Environments

There is one base URL. The key decides the environment: mtk_test_ keys belong to a sandbox programme filled with demo data, mtk_live_ keys to your live programme. Ask us for a sandbox programme to build against; its keys work even before API access is enabled on your live programme.

Rate limits and quotas

Over a limit you get 429 with a Retry-After header (seconds). Higher limits are available on the Enterprise plan; write to info@mentornity.com.

Pagination and sync

Lists return {"object": "list", "data": [...], "has_more", "next_cursor"}. Pass next_cursor back as cursor until has_more is false. limit is 1 to 100 (default 50). Unknown query parameters are rejected with 400, so a typo cannot silently return everything.

For an incremental sync, store the time you started the last run and pass it as updated_since next time. Combine it with webhooks: the webhook tells you something changed, the API gives you the current state.

Errors

Errors use the HTTP status and a JSON body with a stable code and a readable message.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded: 60 requests per minute per key." } }

Every response carries an X-Request-Id header. Quote it when you write to support.

Endpoints

• GET /me Describe the calling key
• GET /programme Get the programme
• GET /members List members
• GET /members/{id} Get a member
• GET /matches List matches
• GET /matches/{id} Get a match
• GET /meetings List meetings
• GET /meetings/{id} Get a meeting

Objects

Timestamps are RFC 3339 in UTC. Fields may be added at any time; ignore the ones you do not know.

Webhooks

Add an HTTPS endpoint in the API & Webhooks tab and choose its events. We POST each event as JSON. The signing secret (whsec_...) is shown once; you can create a new one at any time.

POST /your/endpoint HTTP/1.1
Content-Type: application/json
webhook-id: evt_3f9a1c0d5e7b2a4c6d8e0f12
webhook-timestamp: 1761037200
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "evt_3f9a1c0d5e7b2a4c6d8e0f12",
  "type": "match.started",
  "created_at": "2026-10-21T09:00:00Z",
  "programme_id": "5f2b...",
  "data": { "object": "match", "id": "6651...", "status": "active", ... }
}

Verifying the signature

Signatures follow the Standard Webhooks specification, so its libraries work as they are. The signature is v1, plus the base64 HMAC-SHA256 of webhook-id.webhook-timestamp.body, keyed with the base64-decoded part of your secret after whsec_. Use the raw body as received, before any JSON parsing, and reject timestamps more than five minutes old.

Node.js

import crypto from 'node:crypto';

// secret: "whsec_..." from the admin panel. body: the RAW request body (string or Buffer).
export function verifyWebhook(secret, headers, body) {
  const id = headers['webhook-id'];
  const ts = headers['webhook-timestamp'];
  const sigs = String(headers['webhook-signature'] || '').split(' ');
  if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = crypto.createHmac('sha256', key).update(`${id}.${ts}.${body}`).digest();

  return sigs.some((s) => {
    const [version, value] = s.split(',');
    if (version !== 'v1' || !value) return false;
    const given = Buffer.from(value, 'base64');
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

Python

import base64, hashlib, hmac, time

def verify_webhook(secret: str, headers: dict, body: bytes) -> bool:
    msg_id = headers.get("webhook-id")
    ts = headers.get("webhook-timestamp")
    if not msg_id or not ts or abs(time.time() - int(ts)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    for part in headers.get("webhook-signature", "").split(" "):
        version, _, value = part.partition(",")
        if version == "v1" and hmac.compare_digest(value, expected):
            return True
    return False

Delivery and retries

• Answer with any 2xx within 10 seconds. Do slow work after you answer.
• Anything else is retried 7 more times: after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours.
• Delivery is at least once and not ordered. Deduplicate by webhook-id, and re-read the object from the API when order matters.
• Events are detected within about a minute of the change.
• An endpoint that fails every delivery for 72 hours is paused; turn it back on in the panel. The panel lists the last deliveries with their status and response, and can resend one or send a test event.
• Endpoints must be public HTTPS on port 443, outside mentornity.com. We do not follow redirects.

Versioning and support

This is version 1. Breaking changes only ship in a new major version under a new path (/v2), and v1 then stays available for at least 12 months. New endpoints, fields and event types can be added to v1 at any time.

Questions, higher limits or a sandbox programme: info@mentornity.com. Include the X-Request-Id of the request in question.