Concepts

Multi-tenant model

MEA is strictly multi-tenant. Each external API key belongs to a single tenant. All requests are automatically filtered by the key’s tenant_id: it is impossible to read or write another tenant’s data, and no parameter allows crossing that boundary.

End-to-end encryption (E2EE) constraint

MEA encrypts documents client-side (zero-knowledge): the server holds no user key and never sees the plaintext.

Consequences for the external API:

• A document flagged is_encrypted=true returns 403 DOCUMENT_E2EE_PROTECTED when downloading its content (GET /documents/{id}/content). Metadata remains readable.
• Documents created via the external API are always stored unencrypted (is_encrypted=false, created_by_user_id=null). The external API is a machine-to-machine channel, outside the zero-knowledge perimeter.

If your integration must retrieve the content of encrypted documents, decryption must happen on the human client side via the MEA application — there is no server-side bypass by design.

Rate limiting

Native rate limiting applies to /api/external/v2:

• Fixed 1-minute window, partitioned per API key.
• 60 requests/minute by default (configurable per key).
• Exceeding it → 429 RATE_LIMIT_EXCEEDED.

Implement exponential backoff on the client side and batch your calls (wide pagination rather than many small requests).

Error code conventions

Codes follow the {DOMAIN}_{DESCRIPTION} format in SCREAMING_SNAKE_CASE. Each code is stable (clients depend on them) and maps to exactly one HTTP status.

Always branch your logic on the error.code field, never on the message (which may be translated or reworded).

See the integration guide for complete examples.