User accounts and profiles
Replace a user’s general permission mask
/a/User_setPermissions
Store a complete general permission mask, including the client-admin flag.
When to use this endpoint
Use for the legacy general permissions on an existing tenant user. The full mask replaces permissions; app_permissions, crm_access and role grants are separate.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Session requests use the dispatcher’s CSRF protection when configured; signed requests follow the API-key authentication flow.
Client administrator access is required; Users edit role alone is insufficient.
The dispatcher applies configured TeamAccess user-record scope before the handler. An explicit target outside that scope returns an error; omitted targets use the current user for the scope check. Active/deleted filtering and additional target checks are described below.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Existing positive user ID owned by the current account, with a matching global identity. Missing or unmatched targets return an error. Existing self/main-account restrictions below still apply. |
val | Integer string | Yes | Complete nonnegative integer mask, at most 32767. Missing, blank, negative, fractional, nonnumeric or nested values are rejected. Zero is valid; no per-bit role grant is inferred. |
Example request
$result = FM_api('User_setPermissions', [
'id'=>'1042',
'val'=>'4',
]);Example response
{
"ok": 1
}Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
{"error": "only admins can edit user permissions"} | Caller is not a client administrator. |
{"error": "you cannot edit your own permissions"} | Target is the caller. |
{"error": "user does not exist or is not in your company"} | Tenant-parent lookup fails. |
{"error": "the main FieldMotion account user must have admin access"} | Main identity would lose the admin bit. |
{"error":"missing or invalid parameter: id"} | Target ID is missing or invalid. |
{"error":"user does not exist"} | Owned tenant/global target is absent. |
{"error":"missing or invalid parameter: val"} | Mask is omitted or outside the supported integer range. |
{"error":"Unable to save user changes. Check the saved state before retrying."} | A checked update failed. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Client-admin-only. The owned tenant user and global identity must exist. Non-admin callers receive an explicit JSON permission error; an absent target never receives a success acknowledgement.
- Requires a different user with the current parent; no active/deleted condition is added. The main account cannot lose the client-admin bit, even when another admin edits it.
- This call does not update CRM module access. CRM1 separately calls User_setCrmAccess as part of its admin-toggle workflow. No target-session refresh or explicit session/token revocation occurs.
- When department hierarchy and team access is enabled, the dispatcher wraps this User write in its access-relationship validation and can reject changes that would strand outstanding Jobs. This does not make file storage, session updates or separate global identity writes one atomic operation. Without that wrapper the handler itself has no enclosing transaction; read back saved state after an uncertain failure.
- No collection filtering, pagination, ordering or batch result is provided. Parameters on this page describe the supported scalar/encoded input; malformed nested values are not a supported contract.
- Both persistence results are checked. There is no distributed transaction across global/tenant storage; after an uncertain error inspect the saved mask before retrying.
- A caller cannot edit their own permissions. The main account must retain mask value 1 (bit index 0), the client-admin flag. Several other legacy bits deny actions; preserve unrelated bits.
Side effects
- Updates the global identity row and the tenant user row, with last_edited and an operation-specific edited_uuid; invalidates the employees cache. Both updates are limited by user ID and the authenticated parent account.
- Writes an entry in tenant user activity logs. It does not send an email, notification or password-reset message.
See it in Fieldmotion
CRM1
Open CRM1 User → Main → CRM permissions, or Users permissions bulk editor. Filter User_setPermissions; each request sends a user ID and the full mask.
CRM2
No direct production caller was found in CRM2. Its User layouts use the generic getRequestedDetails/updateData flow instead; do not assume that flow has the same validation or permissions as this legacy route.
Related endpoints
User_setCrmAccess— Configure the separate CRM module mask.User_setAppPermissions— Configure the app mask independently.