Fieldmotion API Getting started

User role access

Replace role-access rows

POST /a/UserRoleAccess_update

Replace every stored access field for a role without rebuilding users’ mobile permission bitmasks.

When to use this endpoint

Use UserRoleAccess_update only for legacy callers that deliberately manage access rows and mobile permission compatibility separately. CRM2 uses UserRoleAccess_updateAccess.

Authentication and permissions

The authenticated context must contain pageUserRole_edit or the global all role permission.

The permission check runs before explicit login validation.

Parameters

ParameterTypeRequiredDescription
roleIDInteger stringYesTarget role ID after integer conversion; it must be greater than zero. Role existence is not checked.
fieldsNative arrayYesComplete list of access-field strings. Values are neither validated against the catalogue nor SQL-escaped.

Example request

$result = FM_api('UserRoleAccess_update', [
	'roleID' => '12',
	'fields' => ['pageUserRoles_view', 'pageUserRoles_edit'],
]);

Example response

{
  "ok": 1
}

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"You do not have the correct permissions to edit roles."}The role-overview edit permission is absent.
{"error":"missing or invalid parameter: roleID"}The key is absent or integer-converts below 1.
{"error":"missing or invalid parameter: fields"}The key is absent.
Runtime warning/type errorfields is not iterable as the expected native array.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Every prior access row for roleID is deleted, then one new row is inserted per supplied field. Duplicate fields are retained.
  • Inserted rows omit last_edited, leaving the schema default 0. A nonexistent role ID can receive orphan access rows.
  • The function does not update users.app_permissions, so mobile behavior can remain inconsistent with stored fields.

Side effects

  • Replaces user_role_accesses rows and invalidates that cache after the delete and insert calls.
  • Does not write generic audit/deletion history, change the role timestamp, or update assigned users.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found.

CRM2

No production CRM2 caller was found; current role screens use UserRoleAccess_updateAccess.

Related endpoints