Environments

Playbooks show full URLs you can paste. Paths without a host are the same resource.

Dev (default in these docs)

Layer	Base URL	Explorer
Core Backend	https://backend-dev.bookdirect.live/public/api/v1/nellalink	Core Backend docs
Middleware Backend	https://middleware-dev.bookdirect.live/api/v1	Middleware Backend docs

Core Backend is served from Laravel public/, so the browser path includes /public. Middleware Backend does not use /public.

Examples:

POST https://backend-dev.bookdirect.live/public/api/v1/nellalink/user/login
POST https://middleware-dev.bookdirect.live/api/v1/nellalink/properties
POST https://middleware-dev.bookdirect.live/api/v1/bookdirect/payments/initialize
POST https://middleware-dev.bookdirect.live/api/v1/nellalink/file-manager/aws/upload-url

Headers every Core Backend call needs

Header	Required	Value
x-api-key	Yes	Public browse key in the Next.js app (NEXT_PUBLIC_API_KEY) for listing active properties. Write key (JWT required) for creates/updates — prefer Middleware Backend for those writes. See Security and IDOR.
Authorization	Writes and private reads	Bearer {access_token} from login
Content-Type	POST / PUT	application/json

The browse key is assumed public. IDOR is Core Backend path settings + Middleware Backend, not frontend.

Headers every Middleware Backend call needs

Header	Required	Value
Authorization	Yes (except PSP webhooks)	Same Core Backend JWT (iss must be nellalink)
x-api-key	When the route declares it	Same site key unless the Middleware Backend folder uses its own
Content-Type	POST / PUT	application/json

Webhooks (Paystack, Squad, Tsara) use the provider signature header, not a user JWT.

Staging and live

Replace the host only. Paths stay the same.

Env	Core Backend host	Middleware Backend host
Dev	https://backend-dev.bookdirect.live	https://middleware-dev.bookdirect.live
Staging	set when promoted	set when promoted
Live	set when promoted	set when promoted

Document new hosts on /next first, then promote.

Standard response envelope (Core Backend and Middleware Backend)

{
  "status": true,
  "status_code": 200,
  "message": "Login successful.",
  "data": {},
  "meta": { "pagination": {} }
}

Errors:

{
  "status": false,
  "status_code": 422,
  "message": "Validation error",
  "error": {
    "error_code": "optional-code",
    "recommendation": ["What to fix"]
  }
}

JWT

• Issuer: nellalink
• Typical access-token life: 30 minutes. Use POST .../user/refresh with a refresh token, or re-login.
• Store data.uuid (user) and data.access_token. Send that uuid as owned_by on creates. Core Backend must reject a mismatch with the JWT.