Connect your systems: the context endpoint

Give GaaS one HTTPS address of your own. When your agent proposes an action, GaaS asks that address for the facts its policies check (is the channel encrypted, is there an active security incident, has the customer consented, what is this agent's spending limit) and decides with them. You answer from your own systems, in one small JSON shape.

Why it matters

Policies decide on facts. When GaaS has no source for a fact, it treats the gap as risk: the context is reported as missing, confidence drops, and a policy that needs the fact to allow an action does not allow it. For example, pol_t1_001 blocks sending payment-card data unless environmental.channel_encryption is true. Your endpoint is how GaaS learns facts only you know.

How it works

Which categories GaaS asks for

You choose which of the six categories your endpoint answers. For each action GaaS asks only for those that matter to it:

GaaS keeps its own history, behaviour and session-trust context; those categories are not asked for.

Set it up

In the dashboard: Settings → Connected systems. Only an organization admin who signed in with two-factor can change it. Enter the address, choose the categories, and give the secret your endpoint expects, if any (sent as Authorization: Bearer … or in a header you name). GaaS then shows you a signing secret, once: store it, because your endpoint uses it to check that requests come from GaaS. Press Test connection; when every category answers correctly you can switch the endpoint on. Changing the address, categories, secret or time limit switches it off until you test again.

The same with the API (admin key to change, operator or admin key to read):

The request

{
  "contract_version": "1",
  "request_id": "ctxreq_5f0c2a9e41d7b3a8c6e2f190",
  "sent_at": "2026-09-29T15:04:05.123456Z",
  "mode": "live",
  "test": false,
  "categories": [
    "environmental",
    "regulatory"
  ],
  "intent": {
    "id": "8c1e1a4e-3f7a-4d8e-9f10-2b7c5d6e7f80",
    "agent": {
      "id": "billing-agent",
      "name": "Billing agent",
      "framework": "langchain"
    },
    "action": {
      "type": "communicate",
      "verb": "send_email",
      "target": {
        "type": "person",
        "identifier": "cust_42",
        "sensitivity": "confidential",
        "jurisdiction": "US-CA"
      },
      "estimated_impact": {
        "reversible": true,
        "financial_exposure_usd": 0,
        "audience_size": 1,
        "data_categories": [
          "PCI"
        ],
        "regulatory_domains": [
          "PCI-DSS"
        ]
      }
    },
    "context_provided": {
      "session_id": "sess_19",
      "user_state": null,
      "environment": {
        "channel": "email"
      }
    }
  }
}

Full schema: context-endpoint-request.v1.json.

Verify the signature

Check every request before you answer it. Reject a timestamp more than five minutes from your clock, so a recorded request cannot be replayed. Python, standard library only:

import hashlib, hmac, time

def verify(secret: str, headers: dict, body: bytes) -> bool:
    """True only if GaaS signed this exact body within the last five minutes."""
    lower = {k.lower(): v for k, v in headers.items()}
    timestamp = lower.get("x-gaas-timestamp", "")
    signature = lower.get("x-gaas-signature", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "v1=" + hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

The response

Answer 200 with Content-Type: application/json:

{
  "contract_version": "1",
  "facts": {
    "environmental": {
      "channel_encryption": true,
      "tls_version": "1.3",
      "protocol": "https"
    },
    "regulatory": {
      "applicable_frameworks": {
        "PCI-DSS": {
          "level": 1
        }
      },
      "cardholder_data_environment": false
    }
  },
  "as_of": {
    "environmental": "2026-09-29T15:04:00Z",
    "regulatory": "2026-09-29T00:00:00Z"
  }
}

• Put each category's facts under facts.<category>. Answer every category GaaS asked for; an empty object is fine.
• as_of is optional: when each category's facts were last true, with a time zone. Old facts count as stale context.
• A fact with the wrong type fails its whole category (the others still count). null means "not known".
• Keys that are not in the table below are kept, so your organization's own policies can read them. Keys are lower case, letters, digits and _; at most 200 per category, nested at most five levels.
• The whole answer must be at most 256 KB.

Full schema: context-endpoint-response.v1.json.

The facts GaaS's policies read

This is every fact a built-in policy checks. Supply the ones you can; a policy that does not get the fact it needs treats it as missing.

Reserved. GaaS sets these itself; a value from your endpoint is dropped and flagged reserved_key_ignored:

• environmental.context_confidence — GaaS computes context confidence itself.
• regulatory.ap2_mandate_present — Set by GaaS's AP2 mandate check.
• regulatory.ap2_mandate_valid — Set by GaaS's AP2 mandate check.
• regulatory.ap2_conditions_met — Set by GaaS's AP2 mandate check.

In the audit record

Every decision's audit record shows your endpoint as one source per category, customer_endpoint_<category>, in stage_2_enrichment.sources_queried, with its status and latency. A category that failed is also in sources_failed, and missing_context gives the reason, for example Source customer_endpoint_environmental returned status timed_out (timeout).

Security

• HTTPS on port 443 only, to a host name with a public TLS certificate. GaaS resolves the name before every call and refuses it if any address is private or internal, then connects to the address it checked.
• Your secrets are encrypted with AWS KMS before they are stored, bound to your organization, and opened only in memory to make the call. GaaS never shows them again, only their last four characters.
• Facts from your endpoint can let an action through that would otherwise be blocked; that is the point, so answer only what your systems know. Every decision records which categories your endpoint supplied.
• An organization admin can switch the endpoint off or remove it at any time, from the dashboard or the API.

Related

• Connectors — built-in integrations
• Shadow Mode — evaluate without enforcing
• Policies — what each policy checks
• Authentication — API keys and roles