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

Only administrators can add new users.

Error message

Only administrators can add new users.

What it means

Thrown by UsersAddController::addPost when a non-admin attempts to POST /users.json to register a new user. User creation is admin-only; the check compares the authenticated user's role against Role::ADMIN before invoking Users->register().

Solutions

1. Authenticate the request with an administrator account's credentials.
2. If you need non-admin signup, that is not supported — invite users via an admin instead.
3. Verify the token/session used is still a valid admin session (re-login).

Example fix

// before
await api.post('/users.json', newUser, { headers: { 'X-User-Token': userToken } }); // user role
// after
await api.post('/users.json', newUser, { headers: { 'X-User-Token': adminToken } });

const me = await api.get('/users/me.json');
if (me.body.role.name !== 'admin') throw new Error('user creation requires an admin account');

function isAdmin(session) { return session?.role?.name === 'admin' || session?.role === 'admin'; }

try { await api.post('/users.json', body); } catch (e) { if (e.status === 403 && /administrators can add/.test(e.message)) { switchToAdminCredentials(); } else throw e; }

When it happens

Trigger: POST /users.json from a logged-in 'user' or 'guest' role account, or with no/invalid authentication where the resolved role is not ADMIN.

Common situations: Scripts using a regular user's API key to provision accounts; expired admin session downgrading the role; self-registration attempts (passbolt requires admin-invited setup).

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

• You are not allowed to access this location.
• You are not authorized to access that location.
• You are not authorized to access that location.
• Access restricted to administrators.
• An administrator user cannot be deleted via SCIM.

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

Appendix: source

Thrown at src/Controller/Users/UsersAddController.php:54

    public function initialize(): void
    {
        parent::initialize();
        $this->Users = $this->fetchTable('Users');
    }

    /**
     * User add action (admin only)
     *
     * @throws \App\Error\Exception\ValidationException if user data does not validate
     * @throws \Exception
     * @return void
     */
    public function addPost()
    {
        $this->assertJson();

        if ($this->User->role() !== Role::ADMIN) {
            throw new ForbiddenException(__('Only administrators can add new users.'));
        }
        $data = $this->request->getData();
        $user = $this->Users->register($data, $this->User->getAccessControl());
        $user = $this->Users->findView($user->id, Role::ADMIN)->first();
        $msg = __('The user was successfully added. This user now need to complete the setup.');
        $this->success($msg, $user);
    }
}

View on GitHub (pinned to 31c1bbc10f)