# DBM API Endpoints and Authentication

This page documents the framework JWT service and the current DBM Platform API route example. The example user, order, health-check, and token-issuing endpoints sometimes shown in generic API tutorials are not registered by this project unless an application adds them.

# Platform API entry point and route prefix

The public entry point is public/index.php. It creates the application through bootstrap/app.php, which loads web routes from bootstrap/web.php and API routes from bootstrap/api.php. The platform mounts the API route file under /api.

For example, bootstrap/api.php declares a route path like /crypto/market/{symbol}. Its effective URL is /api/crypto/market/{symbol}. See the platform route declarations in bootstrap/api.php and application composition in bootstrap/app.php.

# Current API example: crypto market

CryptoMarketApiController exposes market-data and history actions. Its responses use ApiResponder, a consistent JSON response helper available to controllers:

return ApiResponder::error(
    'Cryptocurrency symbol is required.',
    400
);

return ApiResponder::success(
    'Market data retrieved.',
    $marketData
);

A success response has a status, message, and data field. An error response has a status and message field. The older BaseApiController::jsonResponse() helper remains available when an endpoint needs a custom JSON body; ApiResponder is the newer convention used by DBM Platform API controllers.

# JWT service

The framework provides Dbm\Security\Jwt\JwtService for generating, validating, decoding, refreshing, and checking roles or scopes in tokens. It can receive the secret and expiration explicitly, or read API_JWT_SECRET and API_JWT_EXPIRATION from the environment. Construction requires API_ENABLED=true.

use Dbm\Security\Jwt\JwtService;

$jwt = new JwtService();
$token = $jwt->generateToken([
    'sub' => 'user-123',
    'role' => 'member',
    'scopes' => ['market:read'],
]);

if ($jwt->validateToken($token)) {
    $claims = $jwt->decodeToken($token);
}

generateToken() sets the expiration claim (exp) from the configured lifetime. validateToken() checks the signature and that exp is in the future. decodeToken() decodes the payload but does not itself validate the signature or expiration; validate first when trusting claims. refreshToken(), hasRole(), and hasScope() are also available. JwtAuthMiddleware can protect routes using the framework service.

# Environment configuration

API_ENABLED=true
API_JWT_SECRET=replace-with-a-long-random-secret
API_JWT_EXPIRATION=3600

The service currently has a fallback secret if API_JWT_SECRET is missing. Set a strong secret in every deployed environment; never rely on that fallback in production. JWT provides token mechanics, not a complete login or user-management endpoint. The application must authenticate users, decide claims, and register any token endpoint itself.

# Calling the API

Use an HTTP client implementation registered by your application to call the effective platform route, including the /api prefix. The framework's HttpClientInterface is the portable contract; the concrete client and authentication setup depend on the application.

For the general client contract and options, see HTTP Client.

# HTTP status codes

Choose status codes that describe the result of the request. Common values include 200 (success), 201 (created), 400 (invalid request), 401 (unauthenticated), 403 (not authorized), 404 (not found), and 500 (server error). The framework exception middleware can format API exceptions, while controllers can use ApiResponder for explicit success or error responses.