REST API v1 Overview

Base URL: /wp-json/middag-account/v1/

The middag-account REST API exposes 79 endpoints across 18 groups. All endpoints use the WordPress REST API infrastructure with permission_callback on every route.

Authentication Methods

The API supports triple authentication depending on context:

Method	Header / Mechanism	Used By
JWT RS256	Authorization: Bearer {token}	Portal, mobile, third-party
WordPress Nonce	X-WP-Nonce cookie-based	wp-admin (Inertia UI)
WC API Keys	Consumer key + secret (WooCommerce native)	WooCommerce integrations

JWT Details

• Algorithm: RS256 (RSA + SHA-256). Never HS256.
• Access token TTL: 24 hours
• Refresh token TTL: 7 days (mandatory rotation)
• Private key stored outside the webroot
• Payload fields at top level: sub, org, roles, scopes, company

{
    "sub": 42,
    "org": 15,
    "roles": [
        "admin"
    ],
    "scopes": [
        "organization",
        "finances",
        "orders"
    ],
    "company": "middag_br",
    "iat": 1714200000,
    "exp": 1714286400
}

Required Headers

Header	Direction	Required	Value
Authorization	Request	Yes *	Bearer {jwt_token}
X-Middag-Organization	Request	Yes **	Organization ID (int)
X-Middag-Company	Request	No	middag_br or middag_global
Content-Type	Request	Yes (POST/PUT)	application/json

* Except /auth/login, /auth/register, and other public endpoints. ** Except endpoints that do not operate on organization-scoped data.

Response Envelope

Every endpoint returns a consistent JSON envelope:

{
    "success": true,
    "data": {},
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 100,
        "pages": 5
    },
    "message": null,
    "errors": null
}

Field	Type	Always Present	Description
success	boolean	Yes	true for 2xx, false for errors
data	`object	array`	Yes
meta	`object	null`	Yes
message	`string	null`	Yes
errors	`object	null`	Yes

Pagination

List endpoints accept these query parameters:

Parameter	Type	Default	Description
page	int	1	Current page
per_page	int	20	Items per page (max: 100)
order	string	desc	Sort direction: asc or desc
orderby	string	created_at	Sort field
search	string	--	Text search (when supported)

Error Codes

Code	HTTP	When
VALIDATION_ERROR	422	Invalid input fields
AUTHENTICATION_ERROR	401	Missing, expired, or invalid token
AUTHORIZATION_ERROR	403	Insufficient permissions
NOT_FOUND	404	Resource does not exist
CONFLICT	409	Conflicting state
RATE_LIMIT	429	Rate limit exceeded
INTERNAL_ERROR	500	Unexpected server error

Error Response Example

{
    "success": false,
    "data": null,
    "meta": null,
    "message": "Validation failed",
    "errors": {
        "code": "VALIDATION_ERROR",
        "fields": {
            "email": [
                "Email is required"
            ],
            "name": [
                "Name must be at least 2 characters"
            ]
        }
    }
}

Rate Limiting

Endpoint	Limit	Window	Per
/auth/login	5	1 minute	IP
/auth/register	3	1 minute	IP
/auth/forgot-password	3	5 minutes	IP
/auth/resend-verification	3	5 minutes	Email
/auth/refresh	10	1 minute	User ID
Other authenticated endpoints	60	1 minute	User ID

Exceeded requests receive HTTP 429 with a Retry-After header.

Middleware Pipeline

Every authenticated request passes through this middleware chain in order:

1. AuthMiddleware -- Extract and validate JWT, set WP_User in request context
2. PermissionsMiddleware -- Validate role and scopes against route requirements
3. OrganizationMiddleware -- Validate X-Middag-Organization header and membership
4. CompanyMiddleware -- Validate X-Middag-Company header (if route is company-scoped)

Stability Contract

REST API v1 guarantees no breaking changes within v1. New endpoints are additive. Existing fields are never removed. Deprecation comes with 6 months advance notice.

Endpoint Groups

Group	Endpoints	Reference
Auth	12	/auth/*
Organizations	7	organizations.md
Collaborators	8	collaborators.md
Entitlements	6	entitlements.md
Orders	4	orders.md
Invoices	4	invoices.md
Tax Invoices	4	invoices.md
Quotes	5	quotes.md
Licenses	4	licenses.md
Contracts	3	contracts.md
Environments	4	environments.md
Services	3	services.md
Service Requests	4	services.md
Documents	3	--
Downloads	2	--
Affiliates	2	--
Admin	2	--
Webhooks	2	--