What causes "Access restricted to administrators." in passbolt/passbolt_api?

This is expected behavior for non-admins: have the client handle the 403 and hide admin functionality for non-admin roles.

passbolt/passbolt_api · warning · Cake\Http\Exception\ForbiddenException

Access restricted to administrators.

Error message

Access restricted to administrators.

What it means

UserAccessControl::assertIsAdmin() throws Cake's ForbiddenException (HTTP 403) when the encapsulated user's role is not admin. It is a guard used by endpoints/operations reserved for administrators, translating role checks into a standard 403 response.

Solutions

This is expected behavior for non-admins: have the client handle the 403 and hide admin functionality for non-admin roles.
Verify the UserAccessControl was constructed with the correct roleName for the authenticated user (role lookup from session/identity).
If the user should be an admin, update their role in the database to admin and re-authenticate.

Example fix

// before
$this->UserAccessControl->assertIsAdmin(); // 403 for normal users
// after
if (!$this->UserAccessControl->isAdmin()) {
    throw new ForbiddenException(__('This operation is restricted to administrators.'));
}
// or in the template/controller: skip admin actions when role !== Role::ADMIN

Defensive patterns

Strategy: try-catch

Validate before calling

if (!$uac->isAdmin()) {
    // hide/disable admin operations up front for this role
    return $this->response->withStatus(403);
}

Type guard

function isAdminUac(UserAccessControl $uac): bool {
    return $uac->isAdmin();
}

Try / catch

try {
    $uac->assertIsAdmin();
    $this->doAdminOperation();
} catch (\Cake\Http\Exception\ForbiddenException $e) {
    $this->set('error', __('You are not allowed to perform this operation.'));
    return $this->response->withStatus(403);
}

Prevention

Gate admin routes in routes/middleware so non-admins never reach admin controllers.
Check role in the client UI to avoid issuing doomed requests.
Keep roleName resolution in one place so UAC is never built with a wrong role.

When it happens

Trigger: Any controller/service path calling assertIsAdmin() while the current UserAccessControl was built with a non-admin roleName (e.g. 'User'), such as a regular user calling admin-only endpoints like user deletion or role management.

Common situations: Non-admin user hitting admin API routes directly; session/role misconfiguration (UAC built with wrong roleName); tests executing admin operations with a plain-user UAC; frontend showing admin UI to a user whose role was downgraded server-side.

Understand the failure class

Background: "You do not have permission" / 403 Forbidden errors: authenticated but not allowed — causes and fixes across open-source libraries — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at src/Utility/UserAccessControl.php:151

     */
    public function toArray(): array
    {
        return [
            'userId' => $this->userId,
            'rolename' => $this->roleName,
        ];
    }

    /**
     * Allow admins only.
     *
     * @throws \Cake\Http\Exception\ForbiddenException
     * @return void
     */
    public function assertIsAdmin(): void
    {
        if (!$this->isAdmin()) {
            throw new ForbiddenException(__('Access restricted to administrators.'));
        }
    }
}

View on GitHub (pinned to 31c1bbc10f)