9.1Concepts

What an operation is

An operation is one request to change something, recorded as one row in the operations log. There are two kinds:

• Directory operations change something in Active Directory: create, update, move, rename or delete a user, group, computer, organizational unit or other object, change a membership, reset a password, and so on.
• Platform operations change the SYNERGY Management Gateway itself: roles, platform users and their sessions, API keys, operation policies, single sign-on settings, notification rules, MCP tool descriptions, licence and update settings, directory connection records, log stream destinations and telemetry settings. In the log these rows carry a System tag.

Reads are generally not recorded as operations. Some operations are recorded even when they are refused (for example a platform change refused by the permission checks), so the log shows attempts as well as successes.

Who is ever held for approval

Approval in SYNERGY Management Gateway is a control on machine credentials, not on people.

• A person is never held. When you work in the console under your own session, your request either runs or is refused on your permissions. It is never queued for somebody else to approve.
• API keys and AI agents can be held. A request made with an API key (for example from an n8n workflow or a script) or by an AI agent connected through the MCP server can be queued until a person approves it.
• Only directory operations are held. Changes to the platform's own settings are audited, but never queued. An approval step there could stand between an administrator and the screen that repairs access.

Why a request is held

When an API key or agent makes a directory change, the platform decides whether it can run at once or must wait. The reasons below are checked in this order, and the first one that applies is the one recorded on the operation as Why it is waiting:

The texts you will see in the log are, for example:

• "This operation always asks a person before an agent makes it."
• "This agent asks before every change it makes." (a Supervised credential)
• "This agent asks before destructive and security changes." (a Guarded credential)
• "This credential has made, or is asking to make, an unusual number of destructive changes recently, so it is waiting for a person until that settles."
• For a protected target, a sentence naming why the object is protected, or "An object this operation writes is protected."

An object counts as a protected target when:

• it is marked by Active Directory as protected (adminCount=1, typically a current or former member of a privileged group such as Domain Admins);
• it sits inside a container that an administrator has listed as protected for that directory;
• for a delete only, it has "Protect object from accidental deletion" set;
• or it could not be read. When in doubt, the platform treats the object as protected and asks.

For a change that adds a member to a group, both the member and the group are checked, so "add this user to Domain Admins" is held even though the user is an ordinary account.

The three supervision levels (Unsupervised, Guarded, Supervised), protected containers, the "Always ask agents" pin and the volume brake are configured as described in Chapter 10, Operation policies, attribute policies and agent supervision. API key supervision is set as described in Chapter 12, API keys, and agent supervision as described in Chapter 13, AI agents (MCP server).

Requests that are refused instead of held

Some requests cannot be queued and are refused outright:

• A change that carries a password (for example a password reset or a user created with a password) and would have to wait is refused with 403 Agent.ApprovalImpossible. A queued request is stored until somebody decides it, and the platform will not store a password in readable form while it waits. In practice this means no agent can set the password of a protected account, and a Supervised agent cannot reset passwords at all.
• A disabled operation is refused with 400 Operation.Disabled. Disabling is a policy decision, not a queue.

How long a request waits

A queued request expires 72 hours after it was made if nobody decides it. An expired request never runs. If an approver tries to approve it after that, the platform records it as Failed with the message "The approval request has expired." An expired request can no longer be rejected or cancelled; those attempts are refused with Operation.NotPending.

Batches

A batch request (up to 100 items, available on the REST API only) is judged as a whole. If any item would be held, the whole batch is queued as one operation and one decision runs it. A batch is never partly run and partly queued. A batch that would be queued and carries passwords is refused as a whole. See Chapter 15, REST API for integrators.

What the caller sees while a request waits

The caller that made the request is told it is waiting, not that it failed:

• A REST caller receives 202 Accepted with the operation's id, its status, the expiry time, the reason it is waiting and a poll URL (GET /api/operations/{id}), plus Location and Retry-After headers. The poll URL returns only the caller's own operations and needs operations:waiting:list.
• An AI agent receives a result with status: pendingApproval and the operation id, and can check progress with its operation status tool.
• The n8n node either stops with the operation id attached or emits an "approval required" item, depending on its On Approval Required option.

When the operation completes, the poll result includes a result block (the affected object's id, distinguished name, object class and action). For a create, the id is the new object's objectGUID. See Chapter 13, AI agents (MCP server), Chapter 14, n8n integration and Chapter 15, REST API for integrators.

Operation statuses

Every operation has one of five statuses:

There is no separate "Approved" or "Expired" status in the log:

• An approved request runs immediately, so it moves straight from Waiting to Approve to Success or Failed. The approval itself is shown in the operation's approval timeline (approver and time).
• A request that expires unanswered stays recorded as waiting until somebody acts on it; it no longer appears in the requester's waiting list, and an attempt to approve it records it as Failed with the expiry message. On the My Waiting Operations page, such requests are labelled Expired in the Decided section.

Note: Cancelled is deliberately separate from Rejected. Rejected means an approver refused the request; Cancelled means nobody but the requester looked at it. Anything that waits for a decision, such as the n8n "wait for approval" option or an agent checking status, treats Cancelled as final.

Permissions at a glance

What you see in the log is also limited by the directories your active role may use. A row about a directory your role cannot reach is not shown to you, and an operation in such a directory is reported as "not found" if you try to open or decide it. Platform rows that name no directory are visible to every reader of the log. See Chapter 11, Users, roles and permissions.

Approving and rejecting are always a person's act. An API key or an AI agent token can never approve or reject an operation, even if its owner holds operations:approve. Such an attempt is refused with 403 Operation.DecisionRequiresPerson. There is also no approval tool in the MCP server.