Authentication, scopes, and rate limits

API keys

Every API request must send an Authorization: Bearer <key> header. Keys look like:

mc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
mc_test_abcdefghijklmnopqrstuvwxyz0123456789ABCD

The prefix tells you (and any code reviewer) whether the key is live or test data.

How keys are stored

• Mobieus stores only a SHA-256 hash of the key — the plaintext is shown once at creation and is unrecoverable.
• Lookup uses constant-time comparison so attackers can't grind hashes by timing.
• The first ~12 characters are stored separately so the admin UI can identify the key by prefix without ever seeing the secret.

Managing keys

Tenant super-admins manage keys at /admin/api-keys. Settings live at /admin/api/settings.

Every create, edit, and revoke is audit-logged.

Scopes

Every key has one or more scopes. Endpoints check the scope before processing — a key without events:read calling GET /api/v1/events gets 403 insufficient_scope.

Core, webhooks, marketplace, files, moderation

mobieusHelp

mobieusLearn

mobieusKnow

mobieusHealth

A mobieusHealth key only ever reads or writes its own owner's data. Across every /api/v1/health/* endpoint there is no parameter — path, query, or body — that names another member, and the owner must hold an active mobieusHealth seat or the call returns 403 health_no_access. Full reference: mobieusCore API — mobieusHealth. Added in 1.19.0.

One deliberate exception, and it is worth understanding before you build against it: GET /api/v1/buddy/{ownerId}/data/{category} returns another member's health data. It is gated by that member's own explicit sharing grant — no grant, 403 not_shared — the read is audited, and the response is shaped to the detail level they granted. health:read is required. See mobieusBuddy & mobieusChallenge.

Client telemetry

This exists for the mobile apps, which send it on every session. An integration almost never needs it, and it is not granted by default. Added in 1.23.0; before that the endpoint required no scope at all.

Principle of least privilege: only grant the scopes the integration actually needs.

Response headers

Every /api/v1 response carries two headers worth logging:

X-API-Version tracks info.version in the OpenAPI spec. Pin against it if you want to detect a change in the surface you built on.

Plan gate

The public REST API is gated to Pro, Creator, Creator Plus, and Sovereign tenants. Tenants below Pro get 403 plan_gated:

{ "error": { "code": "plan_gated",
             "message": "The public REST API is available on Pro and higher plans. Upgrade in /admin/billing.",
             "current_plan": "starter",
             "required_plans": ["pro", "creator", "creator-plus", "sovereign"],
             "request_id": "req_…" } }

Upgrade in /admin/billing and the API surface lights up immediately — no key re-mint needed.

Tenant isolation

A key is bound to the tenant it was minted in. A mc_live_… key from one community will not authenticate against another, and there is no API surface to query a different tenant's data with it. Tenant scoping happens at the database connection layer, so cross-tenant queries are structurally impossible.

Rate limits

Three layers, evaluated in order:

1. Per-key override — api_keys.rate_limit_per_minute set on /admin/api-keys/{id}/edit. Highest precedence.
2. Tenant default — api_settings.default_rate_limit_per_minute set on /admin/api/settings. Applies when the per-key override is blank.
3. Platform default — api.rate_limit_per_minute in app.ini (currently 600). Fallback when both overrides are blank.

Every response carries:

• X-RateLimit-Limit — the ceiling actually applied to this request
• X-RateLimit-Remaining — what's left in the current 60-second window
• X-RateLimit-Reset — Unix timestamp when the window resets

On exceed you get 429 Too Many Requests plus a Retry-After: <seconds> header. Back off, then retry.

Request IDs

Every response carries X-Request-Id: req_xxxxxxxxxxxxxxxx. The same id appears in the JSON body as request_id. Include it whenever you contact support — it lets us correlate your call with the server log instantly.

Error envelope

Every error response uses the same JSON shape:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid, revoked, or expired.",
    "request_id": "req_3f2b8d9c10ab7c92"
  }
}

Common codes:

Related Pages