Connect API

What is ConnectApi?

App\ConnectApi is the domain for external, integration-focused endpoints added in PR #9603 and ticket FOUND-1273. It exposes selected Core data through JWT-authenticated HTTP APIs with a consistent response envelope, route-level abilities, and Connect API specific exception rendering.

Technicalities

Guard and abilities

Connect API uses the connect-api auth guard from config/auth.php. The guard driver is connect-api-jwt, implemented by App\ConnectApi\Auth\ConnectApiJwtGuard.

JWTs are authenticated by App\ConnectApi\Services\JwtAuthenticator:

• the bearer token iss claim must match an active connect_api_consumers.client_id;
• tokens are verified with the consumer shared_secret using HS256;
• tokens must include exp;
• invalid, expired, inactive, or unknown consumers are treated as unauthenticated.

Consumers are represented by App\ConnectApi\Models\ConnectApiConsumer. Their abilities JSON column stores strings such as orders:read. Route abilities are enforced by the connect-api-ability:<ability> middleware, which delegates to Laravel Gate through ConnectApiConsumer::hasAbility().

Routes and default middleware

Routes live in routes/connect-api.php and are registered by RouteServiceProvider::mapConnectApiRoutes() with the /connect-api prefix.

Every Connect API route receives this default middleware stack:

• api
• auth:connect-api
• iptrace
• db-query-log
• throttle:connect-api

Versioned endpoint paths are defined inside routes/connect-api.php. Add endpoint-specific abilities directly on the route, for example ->middleware('connect-api-ability:orders:read').

Response envelope and exception handling

Controllers should return responses through App\ConnectApi\Http\ConnectApiResponse.

Success response:

{
  "success": true,
  "data": [],
  "error_message": null
}

Error response:

{
  "success": false,
  "data": null,
  "error_message": "Message."
}

App\Exceptions\Handler detects Connect API requests by the auth:connect-api middleware and renders framework exceptions into this envelope. Validation errors return 422, unauthenticated requests return 401, forbidden requests return 403, HTTP exceptions keep their status code, and unhandled errors return 500 with Server Error..

Form requests should also use ConnectApiResponse::error(...) from failedValidation() when they need precise validation messages.

How to add new endpoints

1. Add the controller, request, service, and data objects under app/ConnectApi.
2. Keep controller logic thin: validate input, call the service, return ConnectApiResponse.
3. Use Spatie Data DTOs for response payloads and redaction helpers when exposing sensitive fields.
4. Add the route to routes/connect-api.php under the correct version prefix.
5. Protect the route with connect-api-ability:<ability>.
6. Add or reuse the ability string on the target ConnectApiConsumer.
7. Add feature tests under tests/Feature/ConnectApi and unit tests under tests/Unit/ConnectApi for non-trivial guard, middleware, service, or DTO behaviour.