Web-service integration

local_delegateaccount registers the Delegated account management external service. It is disabled by default, restricted to explicitly authorised users, and does not allow file upload or download. Enable it only after creating a dedicated integration account and assigning the minimum capabilities required for that integration.

Function and capability matrix

Function	Capability	Purpose
local_delegateaccount_get_delegations	local/delegateaccount:view	Read a stable page of delegation records.
local_delegateaccount_get_user_delegations	local/delegateaccount:view	Read one authorised user’s delegation history.
local_delegateaccount_create_delegation	local/delegateaccount:create	Create one delegation idempotently using scalar identifiers.
local_delegateaccount_create_delegations	local/delegateaccount:create	Create a user-by-target matrix idempotently.
local_delegateaccount_update_delegations	local/delegateaccount:update	Apply one validity period and notification decision to selected records.
local_delegateaccount_revoke_delegations	local/delegateaccount:revoke	Logically revoke selected records after explicit confirmation.
local_delegateaccount_get_delegation_activity	local/delegateaccount:viewactivity	Read standard-log activity within one immutable delegation period.
local_delegateaccount_get_session_permissions	local/delegateaccount:view (moodle/site:config for the site)	Read the capabilities of the site and the permission overrides of the site (delegationid 0) or of one delegation.
local_delegateaccount_save_session_permissions	local/delegateaccount:managepermissions (and moodle/site:config for the site)	Change some overrides of the site or of one delegation; permission 0 removes one.
local_delegateaccount_update_session_permissions	local/delegateaccount:managepermissions	Change, or copy from one delegation, the overrides of many delegations: the identifiers given, or all with the filters of a list.

The pages of the plugin also call local_delegateaccount_get_user_list, local_delegateaccount_get_delegation_list, local_delegateaccount_get_delegation_ids, local_delegateaccount_get_activity_list and local_delegateaccount_get_my_accounts. They return what the screens draw (texts in the language of the user, addresses, flags of what can be done) and may change with the screens; integrations should prefer the functions above.

An override can only set 1 (Allow), -1 (Prevent) or -1000 (Prohibit), Moodle’s own values. Allow is refused unless the calling user is a site administrator, also when it is copied from another delegation. Bulk changes are written in batches of 500 delegations and are not limited by Maximum records per bulk action, which still applies to creating, editing and revoking.

local/delegateaccount:manage grants every function above except the ones of session permissions, exactly as it does in the management pages. Setting a specific capability to Prevent or Prohibit in one of the integration user’s system roles still refuses that function, even when the role allows local/delegateaccount:manage. For an inventory-only integration, grant local/delegateaccount:view instead of local/delegateaccount:manage.

Each registered function maps to one dedicated class under classes/external/. The shared delegation_service base is internal, is not registered as a callable function and contains only common validation, creation-result and serialisation helpers.

Safety and limits

• Pages are zero-based and accept between 1 and 100 records.
• Bulk creation is the Cartesian product of the supplied authorised users and target accounts. The site’s Maximum records per bulk action and Maximum delegated accounts per user settings are enforced before any row is created.
• Singular and batch creation share the same domain implementation. Use the singular function for one exact user-target pair and the batch function when every supplied user should receive every supplied target account.
• An existing non-revoked user-target pair returns unchanged; the operation does not create a duplicate.
• The same user cannot be both the authorised user and target account.
• Suspended, deleted, guest, unauthorised and protected site administrator accounts are rejected using the same rules as the web interface.
• Revocation requires confirm=true, remains logical and preserves history. It prevents new delegated sessions and ends the delegated sessions that are already open at once.
• Activity results are clamped to the selected delegation’s own start and end boundary. A later delegation between the same users is a different period.
• Notification rules are identical to the management interface. Service responses never contain message bodies, tokens or credentials.

Notification decision

create_delegation, create_delegations and update_delegations accept an optional notificationmode of always, never or site. When it is omitted, site is used, meaning “let the site decide”. The decision that is stored and applied depends on the Notification policy setting:

Notification policy	always	never	site or omitted
Allow the person creating the delegation to choose (default)	Notify	Do not notify	Notify, as the creation form does by default
Always notify	Notify	Notify	Notify
Never notify	Do not notify	Do not notify	Do not notify

The stored decision is always always or never, so the value returned by the read functions shows what was actually applied. Send notificationmode=never explicitly when an integration must not notify anyone.

Example requests

These examples show parameter shapes only. Replace https://moodle.example with the site URL and provide the token through a secret manager or protected environment variable; never commit a real token.

Create one currently valid delegation without sending a notification:

POST https://moodle.example/webservice/rest/server.php
wstoken=<SECRET>&moodlewsrestformat=json
&wsfunction=local_delegateaccount_create_delegation
&realuserid=120&delegateduserid=450
&timestart=1787356800&timeend=1787961600&notificationmode=never

The singular response identifies the requested pair, its current delegation record and one of three outcomes: created, unchanged or skipped.

Create the complete matrix between two authorised users and three target accounts using one common validity period:

POST https://moodle.example/webservice/rest/server.php
wstoken=<SECRET>&moodlewsrestformat=json
&wsfunction=local_delegateaccount_create_delegations
&realuserids[0]=120&realuserids[1]=121
&delegateduserids[0]=450&delegateduserids[1]=451&delegateduserids[2]=452
&timestart=1787356800&timeend=1787961600&notificationmode=never

That request evaluates six pairs and returns one outcome per pair plus the number of records created. Repeating either creation request is safe: a current relationship is returned as unchanged rather than duplicated.

Read the first 25 active delegations belonging to one authorised user:

GET https://moodle.example/webservice/rest/server.php
?wstoken=<SECRET>&moodlewsrestformat=json
&wsfunction=local_delegateaccount_get_user_delegations
&realuserid=120&page=0&perpage=25&status=active

Revoke two records explicitly:

POST https://moodle.example/webservice/rest/server.php
wstoken=<SECRET>&moodlewsrestformat=json
&wsfunction=local_delegateaccount_revoke_delegations
&delegationids[0]=81&delegationids[1]=82&confirm=1

The numeric identifiers above are fictitious. Client applications should store only the identifiers they require and should not log full responses or request URLs containing credentials.