passbolt/passbolt_api · error · ForbiddenException

Unable to authenticate the guest user with the provided…

Error message

Unable to authenticate the guest user with the provided credentials.

What it means

This ForbiddenException is the catch-all branch of the guest authentication check in UserKeyPoliciesGetSettingsController::assertQueryParameters. When the token lookup throws any exception other than NotFoundException or CustomValidationException, the controller rejects the guest with 'Unable to authenticate the guest user with the provided credentials.' It signals token validation failed in an unexpected way (e.g. a database error), so the caller is denied without leaking details.

Solutions

Check the server error log — the underlying exception is chained and logged — and fix the root cause (usually DB connectivity or missing migrations).
Run database migrations (ddev refresh or cake migrations migrate) to ensure authentication_tokens exists.
Verify database credentials and connectivity in config/app.php.
Retry once the infrastructure issue is resolved; this branch is rarely caused by the client payload.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await get('/user-key-policies/settings', { user_id, token });
} catch (e) {
  if (e.status === 403) {
    // unexpected token-validation failure: check server logs / DB health, retry after infra recovery
  }
  throw e;
}

Prevention

Ensure the database is reachable and migrations have run before invoking installer-related endpoints.
Monitor server error logs; the real cause is the chained exception, not the client payload.
Retry only after fixing the underlying infrastructure issue, not in a tight loop.

When it happens

Trigger: GET /user-key-policies/settings as guest with valid-format user_id and token UUIDs, but the lookup throws an unexpected Exception — typically a database connection/query failure reading authentication_tokens, or an exception from the service/listeners.

Common situations: Database down or misconfigured during setup; authentication_tokens table missing (migrations not run); plugin/event listener on token lookup throwing; transient DB lock or timeout.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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

Appendix: source

Thrown at plugins/PassboltCe/UserKeyPolicies/src/Controller/UserKeyPoliciesGetSettingsController.php:123

        if (!Validation::uuid($authToken)) {
            throw new BadRequestException(__('The authentication token must be a valid UUID.'));
        }

        $errorMsg = __('Unable to authenticate the guest user with the provided credentials.');

        try {
            (new AuthenticationTokenGetService())
                ->getActiveNotExpiredOrFail($authToken, $userId, AuthenticationToken::TYPE_REGISTER);
        } catch (NotFoundException $exception) {
            $errorMsg .= ' ';
            $errorMsg .= __('No registration authentication token found for the given user.');
            throw new BadRequestException($errorMsg, null, $exception);
        } catch (CustomValidationException $exception) {
            $errorMsg .= ' ';
            $errorMsg .= __('The registration authentication token is expired.');
            throw new BadRequestException($errorMsg, null, $exception);
        } catch (Exception $exception) {
            throw new ForbiddenException($errorMsg, null, $exception); // phpcs:ignore
        }
    }
}

View on GitHub (pinned to 31c1bbc10f)