passbolt/passbolt_api · error · Cake\Http\Exception\BadRequestException

API v1 support is deprecated in this version.

Error message

API v1 support is deprecated in this version.

What it means

Passbolt's ApiVersionMiddleware rejects JSON API requests whose version is v1, which was removed from the codebase. Any request still declaring the v1 API (via the URL prefix /v1/... or the version header parsed by getApiVersion) is answered with a 400 BadRequestException instead of being routed.

Solutions

1. Upgrade the client/SDK to a version speaking the current API (v2).
2. Remove the /v1 URL prefix from requests (use the unversioned or /v2 paths).
3. If a custom integration sets the version header, update or remove it so the current default version is used.
4. Interim workaround only: none recommended; the middleware has no bypass — code migration is required.

Example fix

// before
GET /v1/users.json
// after
GET /users.json  (v2 API, current default)

// Client pre-check: strip legacy /v1 prefix before sending
const url = new URL(path, baseUrl);
if (url.pathname.startsWith('/v1/')) {
  url.pathname = url.pathname.replace(/^\/v1/, '');
  console.warn('API v1 is deprecated; rewrote request to', url.pathname);
}

try {
  return await request(path); // path may still be v1
} catch (e) {
  if (e.response?.status === 400 && /API v1 support is deprecated/.test(e.response.data?.header?.message ?? '')) {
    return await request(path.replace(/^\/v1/, '')); // retry on v2
  }
  throw e;
}

When it happens

Trigger: Any JSON request (request->is('json')) whose resolved API version is 'v1' — e.g. calling legacy endpoints under /v1/users.json or sending an API-version header pinned to v1 — through middleware that includes ApiVersionMiddleware.

Common situations: Older CLI clients, browser extensions, or scripts not upgraded after a Passbolt server major upgrade; cached/documented URLs from old integrations; reverse proxies or SDKs still prefixing /v1 to paths.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Could not validate resource data.
• Could not validate the password policies settings.
• Registration is not opened to public. This is due to a…
• The role could not be saved.
• The user does not exist.

AI-assisted analysis of passbolt/passbolt_api@31c1bbc10f (2026-09-17). Data as JSON: /api/errors/532326bb91d38bbd. Report an issue: GitHub.

Appendix: source

Thrown at src/Middleware/ApiVersionMiddleware.php:42

use Psr\Http\Server\RequestHandlerInterface;

class ApiVersionMiddleware implements MiddlewareInterface
{
    /**
     * Throws a bad request if the version passed in the request is not supported.
     *
     * @param \Psr\Http\Message\ServerRequestInterface $request The request.
     * @param \Psr\Http\Server\RequestHandlerInterface $handler The request handler.
     * @return \Psr\Http\Message\ResponseInterface A response.
     * @throws \Cake\Http\Exception\BadRequestException if the API version provided is deprecated
     */
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        /** @var \Cake\Http\ServerRequest $request */
        if ($request->is('json')) {
            $version = $this->getApiVersion($request);
            if ($version === 'v1') {
                throw new BadRequestException('API v1 support is deprecated in this version.');
            }
        }

        return $handler->handle($request);
    }

    /**
     * Get the request api version.
     *
     * @param \Cake\Http\ServerRequest $request Server Request
     * @return string
     */
    public function getApiVersion(ServerRequest $request): string
    {
        $apiVersion = $request->getQuery('api-version');
        // Default to v2 in v3
        if (!isset($apiVersion) || !is_string($apiVersion)) {
            return 'v2';

View on GitHub (pinned to 31c1bbc10f)