ExecutionContext Reference

Version française : ../../fr/guides/execution-context.md

This page describes the signed ExecutionContext that every run receives, how the Context Authority issues and verifies it, and how to validate a document against its contract. Who: developers of agents, tools and MCP servers that must check who they act for, and security officers.

Contract

The schema is contracts/v1/execution-context.schema.json (Execution Context v1). Required fields: schema_version, execution, tenant, identity, workload_identity, delegation, authorization, security, limits, audit, context_integrity. Optional fields: agent, data_governance, models, prompts, tools, rag, multimodal, approvals, storage, observability, finops, runtime_control.

Main blocks

execution: execution_id, environment, started_at, status, entrypoint (required), plus request_id, correlation_id, deadline_at. tenant: tenant_id required, organization_id, project_id. identity: subject_id, subject_type, provider, token_reference. authorization: enforcement, default_decision, fail_closed, plus openfga, opa, effective_rights, break_glass. limits: max_duration_seconds, max_steps, max_subagents, max_depth, max_tool_calls, max_cost, heartbeat_seconds. context_integrity: issuer, issued_at, expires_at, audience, canonicalization, signing_algorithm, key_id, signature.

Issue and verify

The Context Authority (services/control-plane/src/eai/domains/context/authority.py) signs a compact JWS whose header and payload are RFC 8785 canonical JSON, with ES256 or EdDSA. Routes: POST /v1/context/issue, POST /v1/context/verify, GET /v1/context/jwks (offline verification), POST /v1/context/{context_id}/revoke. The default lifetime is EAI_CONTEXT_TTL_SECONDS (900 s), bounded by EAI_CONTEXT_MAX_TTL_SECONDS (3600 s) and by the delegation; the key is referenced by EAI_CONTEXT_SIGNING_KEY_REF. Without a key, issuing fails closed (503 context_authority_unavailable).

const ctx = await client.context.issue({ run_id: "run_1", ttl_seconds: 300 });
await client.context.verify({ token: String(ctx.token) });
const jwks = await client.context.jwks();

Procedures

1. Issue a context for a run. The run and every tool it calls then share one signed statement of the tenant, the identity, the delegation and the limits.

   API: POST /v1/context/issue with run_id, and optionally delegation_id, audience and ttl_seconds.

   Expected result: a token whose lifetime is ttl_seconds (EAI_CONTEXT_TTL_SECONDS by default), cut to the expiry of the delegation when it ends earlier.

   If it fails: 400 context_ttl_exceeded means ttl_seconds is below 30 or above EAI_CONTEXT_MAX_TTL_SECONDS; 503 context_authority_unavailable means no signing key is usable; 403 delegation_expired means the delegation ends before the context could start.

2. Verify a context received by a tool. A tool or an MCP server never trusts a context it did not verify: the signature, the issuer, the audience, the lifetime, the tenant and the revocation are all checked.

   API: POST /v1/context/verify with the token. Offline: fetch the public keys once with GET /v1/context/jwks and check the JWS locally.

   Expected result: the decoded document, every check passed.

   If it fails: 401 with one of the codes of the troubleshooting table; every refusal writes a context.verify audit event.

3. Revoke a context. Revocation ends a context before its expiry, for example when a run is killed or a credential leaks.

   API: POST /v1/context/{context_id}/revoke. Signing keys are listed with GET /v1/context/keys and revoked with POST /v1/context/keys/{kid}/revoke.

   Expected result: the next verification of that context answers 401 context_revoked.

   If it fails: 404 context_not_found means an unknown context; 403 forbidden means you neither created it nor hold tenant_admin or security_officer.

4. Validate a document against the contract. Use it in your tests to prove the documents you build or store follow the schema; see the next section.

   Expected result: the document is valid.

   If it fails: the CLI lists each error with its JSON path.

Settings

Setting	Default	Role
EAI_CONTEXT_TTL_SECONDS	900	default lifetime of a context
EAI_CONTEXT_MAX_TTL_SECONDS	3600	upper bound of a lifetime and of the window of a retired key
EAI_CONTEXT_SIGNING_KEY_REF	none	reference of the signing key
EAI_CONTEXT_ISSUER	urn:eai:context-authority	issuer written in and checked against the token
EAI_CONTEXT_AUDIENCES	eai-control-plane	audiences accepted by POST /v1/context/verify, separated by commas
EAI_CONTEXT_LEEWAY_SECONDS	30	clock tolerance of the lifetime checks
EAI_CONTEXT_REQUIRED	false	every run needs a signed context

Validate a document

An ExecutionContext is validated locally with the SDK or remotely with POST /v1/contracts/{name}/validate.

enterprise-ai validate -f context.json --contract execution-context

Troubleshooting

Status	Code	Cause	Fix
503	context_authority_unavailable	no usable signing key	configure EAI_CONTEXT_SIGNING_KEY_REF
400	context_ttl_exceeded	lifetime below 30 s or above the maximum	ask for a lifetime within the bounds
400, 401	context_wrong_audience	no audience, or an audience not accepted	use an audience of EAI_CONTEXT_AUDIENCES
401	context_malformed	broken structure, encoding or lifetime	send the token as issued
401	context_invalid_signature	wrong algorithm, signature or digest	the token was altered: refuse it
401	context_unknown_key	key id not in the JWKS	refresh GET /v1/context/jwks
401	context_wrong_issuer	issuer different from EAI_CONTEXT_ISSUER	check the issuing platform
401	context_expired	lifetime over	issue a new context
401	context_revoked	context or its delegation revoked	stop the action; issue a new context only with a valid delegation
403	context_tenant_mismatch	context of another tenant	use the credential of the right tenant

Next steps

• ActionContext Reference: the decision recorded for each action.
• API Reference
• MCP Development Guide: check the context in an MCP server.