passbolt/passbolt_api · error · BadRequestException

The authentication token must be a valid UUID.

Error message

The authentication token must be a valid UUID.

What it means

A BadRequestException thrown when the token query parameter fails UUID validation. Like the user_id check, the authentication token must be a valid UUID before AuthenticationTokenGetService performs the lookup.

Solutions

1. Provide the correct authentication token UUID issued by passbolt's token endpoints.
2. Check which token type the client fetched — this endpoint expects a UUID-format authentication token, not a JWT or secret string.
3. Ensure the token is not truncated or altered by URL processing.

Example fix

// before
?user_id=0d2f...&token=abc123   // not a UUID
// after
?user_id=0d2f...&token=9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d

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.token)) throw new Error('token must be a valid UUID authentication token');

const isUuidToken = (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 && /token must be a valid UUID/.test(e.response.data?.message)) {
    // fetch the correct authentication token UUID from the token endpoint
  }
}

When it happens

Trigger: Unauthenticated GET /user-key-policies/settings?user_id=<uuid>&token=<not-a-uuid>, e.g. token passed as a verification token string, JWT, or malformed/truncated value.

Common situations: Sending the wrong token type (e.g. a GPG verify token or JWT instead of the passbolt authentication token UUID); truncated copy-paste; using a token generated by a different endpoint with a non-UUID format.

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.

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

Related errors

• Invalid id
• Please provide a valid request id.
• The authentication token id is invalid.
• The authentication token should 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/9178d6d056e4d962. Report an issue: GitHub.

Appendix: source

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

            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.');
            throw new BadRequestException($errorMsg, null, $exception);
        } catch (Exception $exception) {
            throw new ForbiddenException($errorMsg, null, $exception); // phpcs:ignore
        }

View on GitHub (pinned to 31c1bbc10f)