Delegation and Objective Contracts
How to tell Contexa the scope of work a person gave an agent (operations, targets, period, quantity), and how Contexa compares that scope with the actual request and passes the result to the decision model as facts. The engine never blocks a request for leaving the scope: it only compares, and the model decides.
At a glance
- The delegation the request statesThe delegation stamp read from token claims, the session, request attributes or headers
- Delegation recordNarrowed by the recordThe record a person left (or your business system) narrows the scope; it never widens it
- ContexaScope comparisonWhether the current operation, target and item count are within the delegation and the objective contract, as the fact "drift yes / no"
- AI modelDecisionWeighs the comparison with the rest of the context and decides allow, challenge or block
What one delegation holds
| Field | Meaning | Example |
|---|---|---|
agentId | The agent given the work (required) | report-bot |
objectiveId / objectiveFamily | The work's ID / its kind (an objective family your application declares) | RPT-2026-10 / MONTHLY_REPORT |
objectiveSummary | The work as the delegator described it (up to 1000 characters). Handled as untrusted text in decisions | Write the October sales report |
allowedOperations | Allowed operations, in the words of @Protectable actions (upper-cased) | ["READ"] |
allowedResources | Allowed targets: path patterns or your business IDs | ["/api/reports/**"] |
approvalRequired | Whether the delegator must approve before the work is done | false |
privilegedExportAllowed | Whether privileged data may be exported (empty when not stated) | false |
containmentOnly | Whether the agent may only read or contain | false |
validFrom / expiresAt | Start (default now) / end (required) | 2026-11-30T00:00:00Z |
maxItemsPerRequest / maxItemsTotal | The most items one export may carry / the most items in the session in all (at least 1; none when not stated) | 100 / 1000 |
Each of the operation and target lists holds up to 100 items. A delegation ends when it expires or is revoked, but its record is kept: when it ended is itself a fact the decision weighs.
Ways to state a delegation
| Way | Who | How |
|---|---|---|
| Delegation API | The delegator | POST /contexa/api/agent-delegations. Recorded in the signed-in person's name only. |
| Admin API | An administrator or an integration | POST /contexa/admin/api/agent-delegations (ADMIN role). The delegator, writer and time are given as your records state them. |
| Token claims | The authorization server | delegation_id, objective_*, allowed_*, authorization_details (RFC 9396) and so on (claim names) |
| Business system lookup | Your application | A DelegationRecordLookup bean. The main way when delegations live in your business system (extension points). |
| Session, request attributes, headers | Your application or gateway | Session attributes, request attributes ctxa.delegation.*, headers X-Contexa-* (off by default, trusted proxies required) |
act), an agent's own token or an agent account is refused with 403.
Delegation API
POST /contexa/api/agent-delegations
Content-Type: application/json
{
"agentId": "report-bot",
"objectiveFamily": "MONTHLY_REPORT",
"objectiveSummary": "Write the October sales report",
"allowedOperations": ["READ"],
"allowedResources": ["/api/reports/**"],
"expiresAt": "2026-11-30T00:00:00Z",
"maxItemsPerRequest": 100,
"maxItemsTotal": 1000
}
- On success it returns
201with the delegation. Itsstateis one ofVALID,NOT_STARTED,EXPIREDandREVOKED. - The end must come after the start, and the period may not exceed
contexa.security.zerotrust.agent.delegation-max-validity(default 30 days). Delegate again when the work goes on. GETlists your delegations, latest first, up to 200;POST /{delegationId}/revoke(body{"reason": "..."}) revokes one of yours. A revocation through the admin API requires a reason.- When a person leaves several delegations to the same agent, the one the request names by
delegation_idis used; else the latest started one that holds now; else the latest started one at all, ended ones included. - Each record and revocation writes
AGENT_DELEGATION_RECORDEDorAGENT_DELEGATION_REVOKEDto the audit log with who did it. Deleting the delegator's account deletes that person's delegations too.
A delegation record only narrows the scope
When the delegation a token or session states differs from the delegation record, Contexa always uses the narrower one. However broad the token, the record bounds the scope.
Delegation the token states
- Operations READ, EXPORT
- Targets
/api/** - Ends 18:00
- No item limit
Delegation record
- Operations READ
- Targets
/api/reports/** - Ends 17:00
- 100 items per request
Delegation the decision uses
- Operations READ
- Targets
/api/reports/** - Ends 17:00
- 100 items per request
| Item | Rule |
|---|---|
| Objective | The record's objective when they differ |
| Allowed operations and targets | The items both state. When they share none, the record's list (an empty list means "not stated" and would widen the scope) |
| Approval required, containment only | Required when either requires it |
| Privileged export | Allowed only when neither denies it |
| End, item limits | The earlier end, the lower limit |
| A record for another agent | Not applied |
The lookup result is kept in the decision context as delegationRecordLookup: FOUND (applied), NOT_FOUND (no record; the stated delegation as is), AGENT_MISMATCH (a record for another agent) or FAILED (the lookup failed). The items the record overrode are kept as conflicts, with the record's writer and time. A person's own request is never looked up.
Standing delegation of an autonomous agent
An autonomous agent has no delegator. Contexa then looks once more for the delegation the agent's sponsor recorded for it and applies it with the same rules as a standing delegation. The sponsor records it through the delegation API for that agent. The agent still works in its own name, so the request is not marked as delegated.
Objective contracts
Your application can declare, for each objective family, the operations and resource families the work needs. When a delegation states no allowed operations or resource families of its own, the contract is what it is compared with.
contexa:
security:
zerotrust:
agent:
objective-contracts:
MONTHLY_REPORT: # the delegation's objectiveFamily
operations: [READ] # the words of @Protectable actions
resource-families: [REPORT] # the words of @Protectable category
max-export-items: 500 # the most items one export may carry
- Contexa already knows its own security objective families (audit, containment, learning and so on); a contract your application declares under the same name takes their place.
- To declare contracts in code, declare an
ObjectiveContractSourcebean. Contexa reads its own contracts, then the settings', then the source beans'; a later contract of the same family replaces the earlier one. - The settings also accept
read-onlyandprivileged-export-allowed, but the current version does not use them in the scope comparison. A privileged export is compared against the delegation'sprivilegedExportAllowed.
Drift: the engine compares, the model decides
For each request the engine compares the items below and puts the result in the decision context as "drift yes / no" with the comparison sentences. When there is nothing to compare, it records the comparison as incomplete.
| Comparison | Against |
|---|---|
| Is the current operation allowed? | The delegation's list, else the contract's operations. An unknown operation is not compared |
| Is the current resource family allowed? | The delegation's list, else the contract's resource-families |
| Does the current target match the allowed paths or IDs? | The path patterns and IDs in the delegation's allowedResources |
| Another operation under a containment-only delegation? | Only read, query and contain are within it |
| Is the exported item count within the limits? | The contract's max-export-items, the delegation's maxItemsPerRequest, and the session total against maxItemsTotal |
| An export under a delegation that forbids privileged export? | The delegation's privilegedExportAllowed = false |
- Item counts are compared only when your application states them. Put the request's item count in the request attribute
ctxa.context.requestItems(orrequestItems). - No rule forces a decision because of drift. The model decides from the facts. When the model cites
DELEGATION_SCOPE_DRIFT, Contexa only checks that the fact is really in the context.
Checking the delegation in policy expressions
Apart from the model's decision, URL and method policies can check a delegation deterministically. These expressions read the request's delegation stamp (token, session, ...); the record-narrowed delegation is used in the model's decision.
| Expression | Meaning |
|---|---|
isAgent() / isDelegatedAgent() / isAutonomousAgent() | Whether an agent makes the request / a delegated agent / an autonomous agent |
agentId / isAgentIn('a', 'b') | The requesting agent's ID / whether it is one of these |
delegatorId | The delegator (for a delegated agent) |
delegationChainDepth / delegationChainDepthAtMost(n) | The delegation chain depth (0 for a person or an autonomous agent, 1 for a direct delegation) / whether it is at most n |
delegationAllowsOperation('READ') | Whether the delegation allows the operation |
delegationAllowsResource('/api/reports/1') | Whether the delegation allows the target (a listed item ending in * covers every target starting with what precedes it) |
delegationRequiresApproval() | Whether the delegation requires the delegator's approval |
isDelegatedAgent() and delegationAllowsOperation('READ') and delegationChainDepthAtMost(1)
The confirmation and call-count expressions (agentRequestConfirmed(), agentCallsInLastMinuteAtMost(n)) are in Stop, Confirm, Limit. The full list is in AI Security Expressions.
Settings
Token claim names (contexa.bridge.delegation.token.*)
| Setting | Default |
|---|---|
enabled | true |
actor-claims / may-act-claims | [act] / [may_act] (may_act is kept as information only) |
client-id-claims / agent-id-claims | [azp, client_id, appid] / [agent_id, agentId] |
tenant-claims / delegation-id-claims | [tid, tenant_id] / [delegation_id, delegationId] |
subject-type-claims / user-subject-types | [idtyp, sub_profile] / [user] |
scope-claims / authorization-details-claims | [scope, scp] / [authorization_details] |
objective-id-claims / objective-family-claims / objective-summary-claims | [objective_id, objectiveId] / [objective_family, objectiveFamily] / [task_purpose, objective_summary, objectiveSummary] |
allowed-operations-claims / allowed-resources-claims | [allowed_operations, allowedOperations] / [allowed_resources, allowed_resource_families, allowedResources] |
approval-required-claims / privileged-export-allowed-claims / containment-only-claims | [approval_required, approvalRequired] / [privileged_export_allowed, privilegedExportAllowed] / [containment_only, containmentOnly] |
expires-at-claims | [delegation_expires_at, execution_expires_at, delegationExpiresAt]. Without one, a delegation ends no later than the token |
The agent markers (agent-actor-markers, delegated-markers, agent-client-ids) are in How Contexa recognizes an agent. The session, request attribute and header settings (contexa.bridge.delegation.session.*, request-attributes.*, headers.*) are in bridge settings.
Other settings
| Setting | Default | Meaning | When to change |
|---|---|---|---|
contexa.security.zerotrust.agent.delegation-max-validity | 30d | The longest a delegation recorded through the delegation API may last | To allow longer delegations (a quarter's work) or bound them tighter |
contexa.security.zerotrust.agent.objective-contracts.<family>.* | Empty | Objective contracts | To declare your objectives |
contexa.auth.oauth2.delegation-claim-enabled | true | Contexa's authorization server puts the delegation_id of the delegation in force in exchanged tokens (CONTEXA_OWNED) | false to keep delegation IDs out of exchanged tokens |
Extension points
Reading delegations from your business system
When delegations already live in your approval or business system, connect them with one DelegationRecordLookup bean. With the bean declared, Contexa applies its record to every agent request.
@Bean
DelegationRecordLookup delegationRecordLookup(WorkOrderRepository workOrders) {
return query -> workOrders
.findActive(query.delegatorId(), query.agentId(), query.requestedAt())
.map(order -> new DelegationRecord(
order.id(), order.requester(), order.agentId(),
order.taskId(), "MONTHLY_REPORT", order.title(),
List.of("READ"), List.of("/api/reports/**"),
false, false, false,
order.dueAt(), order.approver(), order.approvedAt(),
100, 1000));
}
- It is called on the analysis thread, once for each request that names an agent or a delegation. Return
Optional.empty()when no record matches. An exception is recorded as a failed lookup and the decision continues with the stated delegation. - Return ended delegations too. When a delegation ended is a fact the decision weighs.
- When
query.standing()istrue, it is the lookup of an autonomous agent's standing delegation, anddelegatorIdis the agent's sponsor.
| Bean | When you need it | Default |
|---|---|---|
DelegationRecordLookup | Delegations live in your business system | Looks up Contexa's delegation store |
DelegationRegistry | To change the delegation store | JDBC with the Contexa database (ctxa_agent_delegation_record table), else in memory |
DelegationContextProvider (add) / RecordedDelegationContextProvider (replace) | To add delegation facts or change the narrowing rules | The narrowing rules above |
DelegationStampResolver (add) | To read delegations from another channel (ordered by @Order) | Five: token, session, request attributes, headers, agent account |
ObjectiveContractSource | To declare objective contracts in code | The settings' contracts only |