passbolt/passbolt_api · error · InvalidVerifyTokenException

Invalid verify token format.

Error message

Invalid verify token format.

What it means

Passbolt's JWT verify-token endpoint requires the verify token to be a UUID string. VerifyTokenValidationService::validateFormat rejects any missing, non-string, or non-UUID token value with InvalidVerifyTokenException, which the client sees as 'Invalid verify token format.' This guards the nonce lookup against malformed input before any database query runs.

Solutions

1. Generate the verify token as a valid UUID (e.g. the value issued by the server / Text::uuid()) and resend the request
2. Check the client is actually reading the stored token field and not an empty/undefined variable
3. Ensure the token is sent as a plain JSON string, not nested in an object or array
4. Update the passbolt browser extension/client to a version compatible with the JWT verify-token API

Example fix

// before
const res = await fetch('/jwt/verify.json', {body: JSON.stringify({verify_token: localStorage.token})});
// after
if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(localStorage.token ?? '')) {
  throw new Error('verify token must be a UUID');
}
const res = await fetch('/jwt/verify.json', {body: JSON.stringify({verify_token: localStorage.token})});

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 (typeof token !== 'string' || !UUID_RE.test(token)) throw new Error('verify token must be a UUID string');

function isUuid(v: unknown): v is string {
  return 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);
}

try { await api.verifyToken(token, userId); } catch (e) { if (e.response?.status === 400) promptUserToRestartSetup(); else throw e; }

When it happens

Trigger: POST/GET to the JWT verify-token endpoint with a missing, empty, non-string (e.g. array/integer), or non-UUID verify token; calling VerifyTokenValidationService::validateToken() directly with a malformed token as the second argument.

Common situations: Client code truncates or mangles the token when storing it in localStorage; a test harness passes a placeholder like 'test-token' instead of a UUID; the token is sent URL-decoded/percent-encoded or wrapped in extra characters; a very old client version sends a differently formatted token.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid user ID format.
• The identifier should be a valid UUID.
• The identifier should be a valid UUID.
• The metadata key ID should be a valid UUID.
• The refresh token should be a valid UUID.

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

Appendix: source

Thrown at plugins/PassboltCe/JwtAuthentication/src/Service/VerifyToken/VerifyTokenValidationService.php:91

        }
    }

    /**
     * Assert verify token is a UUID
     *
     * @param mixed $verifyToken token
     * @return void
     * @throws \Passbolt\JwtAuthentication\Error\Exception\VerifyToken\InvalidVerifyTokenException if the format is not valid.
     * @throws \Cake\ORM\Exception\PersistenceFailedException
     */
    protected function validateFormat(mixed $verifyToken): void
    {
        if (
            !isset($verifyToken) ||
            !is_string($verifyToken) ||
            !Validation::uuid($verifyToken)
        ) {
            throw new InvalidVerifyTokenException(__('Invalid verify token format.'));
        }
    }

    /**
     * Assert verify token is a UUID
     *
     * @param string $userId User ID
     * @return void
     * @throws \Passbolt\JwtAuthentication\Error\Exception\VerifyToken\InvalidVerifyTokenException if the user ID is not a UUID.
     * @throws \Cake\ORM\Exception\PersistenceFailedException
     */
    protected function validateUserId(string $userId): void
    {
        if (!Validation::uuid($userId)) {
            throw new InvalidVerifyTokenException(__('Invalid user ID format.'));
        }
    }

View on GitHub (pinned to 31c1bbc10f)