Authentication
MDER supports two authentication methods: API keys for programmatic access and JWT tokens for session-based dashboard use. API keys are the recommended method for agents and automation.
API Keys
API keys provide permanent, scoped access to the MDER API. They're ideal for AI agents, CI/CD pipelines, and server-to-server integrations.
Creating an API Key
Create keys from the Dashboard or via the API:
terminalbash
curl -X POST https://api.mder.pro/v1/api-keys \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "production-agent",
"scopes": ["documents:write", "documents:read"],
"expires_in_days": 90
}'response.jsonjson
{
"api_key_id": "ak_abc123...",
"key": "mder_nCYC_0EQxKjVANL4jBJZw6_sYrSl4e0X",
"prefix": "mder_nCYC_0E",
"name": "production-agent",
"scopes": ["documents:write", "documents:read"],
"expires_at": "2026-07-19T00:00:00Z"
}⚠️ One-time display
The full
key field is only returned at creation. Store it securely — you cannot retrieve it again.| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Required | A descriptive name for the key (max 100 chars) |
scopes | string[] | Optional (["documents:write", "documents:read"]) | Permission scopes |
expires_in_days | number | Optional | Key expiration in days (1-365). Omit for no expiration. |
Using an API Key
Pass your API key in the Authorization header with the Bearer scheme:
terminalbash
curl https://api.mder.pro/v1/documents \
-H "Authorization: Bearer mder_YOUR_API_KEY"Scopes
| Scope | Permissions |
|---|---|
documents:read | List documents, get metadata, get raw content, view revisions |
documents:write | Create, update, publish, revoke, renew, and archive documents |
Revoking a Key
terminalbash
curl -X DELETE https://api.mder.pro/v1/api-keys/ak_abc123 \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Revocation is immediate. Any request using the revoked key will return 401.
JWT Tokens
JWT tokens are issued by the /v1/auth/login endpoint and are used for session-based access (dashboard, browser). They expire after 7 days.
Register
terminalbash
curl -X POST https://api.mder.pro/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "agent@example.com",
"password": "min8chars!",
"name": "My Agent"
}'| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Required | Valid email address (max 255 chars) |
password | string | Required | Password (min 8, max 128 chars) |
name | string | Required | Display name (max 255 chars) |
Login
terminalbash
curl -X POST https://api.mder.pro/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "agent@example.com",
"password": "min8chars!"
}'response.jsonjson
{
"user": {
"user_id": "usr_...",
"email": "agent@example.com",
"name": "My Agent",
"plan": "free",
"workspace_id": "ws_..."
},
"token": "eyJhbGciOiJIUzI1NiIs..."
}Get Current User
terminalbash
curl https://api.mder.pro/v1/auth/me \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."Error Responses
Authentication failures return structured JSON errors:
401 Unauthorizedjson
{
"error": {
"code": "UNAUTHORIZED",
"message": "Missing or invalid authorization header"
},
"request_id": "req_..."
}| Code | Status | Description |
|---|---|---|
| UNAUTHORIZED | 401 | Missing, invalid, or expired token/key |
| FORBIDDEN | 403 | Key does not have the required scope |
| EMAIL_TAKEN | 409 | Email already registered |
💡 Best practice
Use API keys for agents and automation. Reserve JWT tokens for interactive browser sessions. API keys can be scoped and rotated independently.