passbolt/passbolt_api · error · BadRequestException

The user ID must be a valid UUID.

Error message

The user ID must be a valid UUID.

What it means

A BadRequestException thrown when the provided user_id query parameter fails UUID validation before guest authentication is attempted. The controller validates both identifiers' format up front to avoid pointless token lookups.

Solutions

1. Supply the user's UUID (36-char, e.g. 0d2f5eaa-...), obtainable from the users API or admin console.
2. Fix client code that passes email/username instead of the user ID; resolve it to a UUID first.
3. Verify the value survives URL encoding (no stripped hyphens or truncation).

Example fix

// before
?user_id=admin@passbolt.test&token=9a1b...
// after
?user_id=0d2f5eaa-6c3a-4c1f-9f2e-1b7d8a9c0d1e&token=9a1b...

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
if (!UUID_RE.test(params.user_id)) throw new Error('user_id must be a valid UUID');

const isUuid = (v) => typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v);

catch (e) {
  if (e.response?.status === 400 && /valid UUID/.test(e.response.data?.message)) {
    // fix the offending identifier before retrying; do not retry as-is
  }
}

When it happens

Trigger: Unauthenticated GET /user-key-policies/settings?user_id=<not-a-uuid>&token=<uuid>, e.g. user_id passed as an email address, username, integer ID, empty string, or truncated value.

Common situations: Passing a username or email instead of the user's UUID; copy-paste truncation of the UUID; client code using a legacy non-UUID identifier; URL encoding issues corrupting the parameter.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Invalid id
• Please provide a valid request id.
• The authentication token id is invalid.
• The authentication token must be a valid UUID.
• The comment id is not valid.

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

Appendix: source

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

                // session confusion: If user is logged in but still authentication token is provided we consider it bad request.
                throw new BadRequestException(__('Conflicting authentication parameters, provide user_id/token only when the user is not already signed in.')); // phpcs:ignore
            }

            return;
        }

        $userId = $this->getRequest()->getQuery('user_id');
        $authToken = $this->getRequest()->getQuery('token');

        if (is_null($userId) || is_null($authToken)) {
            throw new UnauthorizedException(
                __('You are not authorized to access this location.') . ' ' .
                __('Sign-in to passbolt, or provide a valid user ID and authentication token.')
            );
        }

        if (!Validation::uuid($userId)) {
            throw new BadRequestException(__('The user ID must be a valid UUID.'));
        }

        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.');

View on GitHub (pinned to 31c1bbc10f)