contexa-core Agent security

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

From a delegation to decision factsThe delegation a request states is narrowed by the delegation record, then compared with the actual request.
  1. The delegation the request statesThe delegation stamp read from token claims, the session, request attributes or headers
  2. Delegation recordNarrowed by the recordThe record a person left (or your business system) narrows the scope; it never widens it
  3. ContexaScope comparisonWhether the current operation, target and item count are within the delegation and the objective contract, as the fact "drift yes / no"
  4. AI modelDecisionWeighs the comparison with the rest of the context and decides allow, challenge or block

What one delegation holds

FieldMeaningExample
agentIdThe agent given the work (required)report-bot
objectiveId / objectiveFamilyThe work's ID / its kind (an objective family your application declares)RPT-2026-10 / MONTHLY_REPORT
objectiveSummaryThe work as the delegator described it (up to 1000 characters). Handled as untrusted text in decisionsWrite the October sales report
allowedOperationsAllowed operations, in the words of @Protectable actions (upper-cased)["READ"]
allowedResourcesAllowed targets: path patterns or your business IDs["/api/reports/**"]
approvalRequiredWhether the delegator must approve before the work is donefalse
privilegedExportAllowedWhether privileged data may be exported (empty when not stated)false
containmentOnlyWhether the agent may only read or containfalse
validFrom / expiresAtStart (default now) / end (required)2026-11-30T00:00:00Z
maxItemsPerRequest / maxItemsTotalThe 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

WayWhoHow
Delegation APIThe delegatorPOST /contexa/api/agent-delegations. Recorded in the signed-in person's name only.
Admin APIAn administrator or an integrationPOST /contexa/admin/api/agent-delegations (ADMIN role). The delegator, writer and time are given as your records state them.
Token claimsThe authorization serverdelegation_id, objective_*, allowed_*, authorization_details (RFC 9396) and so on (claim names)
Business system lookupYour applicationA DelegationRecordLookup bean. The main way when delegations live in your business system (extension points).
Session, request attributes, headersYour application or gatewaySession attributes, request attributes ctxa.delegation.*, headers X-Contexa-* (off by default, trusted proxies required)
An agent cannot record a delegation. A delegation must be a person's word, so a call to the delegation API with a token obtained for a person (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 201 with the delegation. Its state is one of VALID, NOT_STARTED, EXPIRED and REVOKED.
  • 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.
  • GET lists 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_id is 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_RECORDED or AGENT_DELEGATION_REVOKED to 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.

Narrowing exampleOperations: only those both state. Targets: no item in common, so the record's list. End: the earlier. Limit: the lower.

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
ItemRule
ObjectiveThe record's objective when they differ
Allowed operations and targetsThe 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 onlyRequired when either requires it
Privileged exportAllowed only when neither denies it
End, item limitsThe earlier end, the lower limit
A record for another agentNot 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 ObjectiveContractSource bean. 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-only and privileged-export-allowed, but the current version does not use them in the scope comparison. A privileged export is compared against the delegation's privilegedExportAllowed.

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.

ComparisonAgainst
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 (or requestItems).
  • 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.

ExpressionMeaning
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
delegatorIdThe 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.*)

SettingDefault
enabledtrue
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

SettingDefaultMeaningWhen to change
contexa.security.zerotrust.agent.delegation-max-validity30dThe longest a delegation recorded through the delegation API may lastTo allow longer delegations (a quarter's work) or bound them tighter
contexa.security.zerotrust.agent.objective-contracts.<family>.*EmptyObjective contractsTo declare your objectives
contexa.auth.oauth2.delegation-claim-enabledtrueContexa'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() is true, it is the lookup of an autonomous agent's standing delegation, and delegatorId is the agent's sponsor.
BeanWhen you need itDefault
DelegationRecordLookupDelegations live in your business systemLooks up Contexa's delegation store
DelegationRegistryTo change the delegation storeJDBC with the Contexa database (ctxa_agent_delegation_record table), else in memory
DelegationContextProvider (add) / RecordedDelegationContextProvider (replace)To add delegation facts or change the narrowing rulesThe narrowing rules above
DelegationStampResolver (add)To read delegations from another channel (ordered by @Order)Five: token, session, request attributes, headers, agent account
ObjectiveContractSourceTo declare objective contracts in codeThe settings' contracts only