Skip to Content
Getting started

Getting started with the external API

MEA’s external public API (/api/external/v2/*) lets your business applications (ERP, third-party integrations) archive and read documents programmatically, without any human interface. The API is regional: use https://api.eu.mearchiver.com (EU) or https://api.us.mearchiver.com (US). A key may be restricted to specific archive types and can only modify archives it created itself (provenance).

1. Obtain an API key

External API keys are created by a tenant administrator from Settings → Security → External API keys. A key has the form:

mea_ext_{prefix}_{secret}
  • mea_ext_ — fixed prefix distinguishing an external key from an inter-instance synchronization key (mea_). The two are never interchangeable.
  • {prefix} — public identifier of the key (visible in logs).
  • {secret} — secret part, shown only once at creation time. Store it in a secrets vault, never in code.

2. The scopes model

Each key carries one or more scopes. A request is rejected (400 EXTERNAL_API_KEY_INVALID_SCOPES) if the key lacks the scope required by the endpoint.

ScopeAllows
external:archives:readList and read archive folders
external:archives:writeCreate and update archive folders
external:documents:readRead document metadata and content
external:documents:writeUpload documents

Apply the principle of least privilege: grant only the scopes strictly required by the integration.

3. The authentication header

Every request must carry the key in the X-Api-Key header:

X-Api-Key: mea_ext_a1b2c3_YOUR_SECRET

The matching authentication scheme is ExternalApiKey. No other method (Bearer JWT, cookie) is accepted on /api/external/v2.

4. First authenticated request

List the archive types your key is allowed to use, then the (approved) archives:

curl -s https://api.eu.mearchiver.com/api/external/v2/archive-types \
  -H "X-Api-Key: mea_ext_a1b2c3_YOUR_SECRET"
 
curl -s https://api.eu.mearchiver.com/api/external/v2/archives \
  -H "X-Api-Key: mea_ext_a1b2c3_YOUR_SECRET"

5. The response envelope

Every response uses a stable snake_case JSON envelope. List endpoints return a paged object (items/total/offset/limit):

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "8f1c0e2a-3b4d-4e5f-9a0b-1c2d3e4f5a6b",
        "title": "Supplier contracts 2026",
        "submission_status": "VALIDATION_APPROVED",
        "created_at": "2026-06-08T09:30:00Z"
      }
    ],
    "total": 1,
    "offset": 0,
    "limit": 50
  }
}

On error, the envelope carries a typed error object:

{
  "success": false,
  "error": {
    "code": "EXTERNAL_API_KEY_INVALID_SCOPES",
    "message": "The API key does not have the required scopes."
  }
}

Continue with the concepts then the integration guide.

WelcomeLocal Agent