EMPO Academy Docs
API quickstart

API & MCP

API & MCP overview

EMPO Academy exposes two surfaces for programmatic access — one for HTTP scripts (REST), one for AI agents (MCP). Both authenticate with the same bearer-token API key you mint at /dashboard/api-keys.

Two ways to talk to EMPO

  • REST — https://academy.empomm.com/api/v1/*. JSON in, JSON out. Standard HTTP status codes. Curl, Postman, n8n, Make, custom scripts.
  • MCP (Model Context Protocol)— the new wire format used by Claude, Cursor, OpenAI Agents SDK, and other AI clients. We host a Streamable HTTP endpoint at /api/mcp; there’s also a stdio npm package for local use.

Who can use it

  • Admins— full access to courses, certificates (including external Training & Consultancy), and notification templates.
  • Instructors— access scoped to their own courses (or courses where they’re a collaborator). External-T&C certificate operations stay admin-only.
  • Students— cannot mint API keys today.

What you can do

14 tools / endpoints, grouped:

  • Courses: list, get, create, update, status (publish/private/archive), create module, create lesson
  • Certificates: issue single, issue batch (up to 200), revoke, resend email
  • Notifications: list email templates, update template (subject / greeting / CTA / footer / enabled)

Security model in one paragraph

Tokens are 256-bit, generated client-side at mint time, and stored only as SHA-256 hashes — the plaintext is shown once and never again. Every request resolves the token to its owning user, then runs the same permission checks the UI uses (e.g. requireCourseEdit, canManageCert). Revoking a key takes effect immediately. Read more under Scopes & permissions.

Rate limits

60 requests/minute per API key, 120/minute per client IP. The stricter verdict wins. Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers; 429s also set Retry-After (seconds). MCP requests additionally cap at 500 KB body size (413 on overflow). Need higher limits for a real integration? Email academy@empomm.com before pointing prod traffic.

Auditing & usage

Every authenticated call writes one row to api_request_logs (~30-day retention). Owners can see their own activity at /dashboard/api-keys/<id>/usage— 30-day call count, error rate, average duration, last error, and the last 25 calls. Admins see platform-wide rollup at /dashboard/admin/ops.

Next steps