{
  "schemaVersion": "1.0",
  "title": "Identity and trust",
  "description": "Use this page to decide which identity values an AIP implementation may trust. It covers caller authentication, tenant and provider-account selection, credential resolution, operational reads, and connector dispatch. It is for gateway, runt",
  "canonical": "https://getaip.org/docs/concepts/identity-and-trust",
  "route": "/docs/concepts/identity-and-trust",
  "source": "docs/concepts/identity-and-trust.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Core Concepts",
  "documentType": "Concept",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "97be86e9efedf07ecf1783b03800f683f107fb04",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/concepts/identity-and-trust.md",
    "txt": "/docs/download/concepts/identity-and-trust.txt",
    "json": "/docs/download/concepts/identity-and-trust.json",
    "pdf": "/docs/download/concepts/identity-and-trust.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Identity and trust\ndescription: Separate identity claims from authenticated and deployment-resolved authority in AIP\nkind: explanation\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Identity and trust\n\nUse this page to decide which identity values an AIP implementation may trust.\nIt covers caller authentication, tenant and provider-account selection,\ncredential resolution, operational reads, and connector dispatch. It is for\ngateway, runtime, connector, and platform developers.\n\nThe central rule is simple: identity carried in an AIP payload is a claim, not\nproof. A production path first establishes an actor at a transport or signature\nedge, then enriches that actor from deployment-owned data. The runtime executes\nwith the enriched context and replaces caller-supplied action identity before a\nhandler sees the action.\n\nThis page describes the reviewed Rust implementation of AIP 1.0 at source\nrevision `97be86e9efedf07ecf1783b03800f683f107fb04`. A deployment still owns its\nidentity provider, issuer trust, tenant directory, credential store, key\nlifecycle, and policy. The implementation exposes primitives for those\nboundaries; it does not create a universal identity federation.\n\n## Keep four identity layers separate\n\n| Layer | Main type or record | Authority | Purpose |\n|---|---|---|---|\n| Wire claim | `Principal`, `Envelope.from`, and `Action.identity` | Caller-controlled until verified | Names actors and supplies identity lookup hints |\n| Authenticated actor | `AuthenticatedPrincipal` | Transport authenticator or trusted DID binding | Records the proven principal, scheme, issuer, scopes, time, expiry, and optional credential fingerprint |\n| Trusted enrichment | `ResolvedIdentity` | Deployment-owned identity resolver | Adds verified tenant membership, an opaque credential handle, and sanitized product identity |\n| Execution boundary | `MessageContext` and, for fleets, `RouteAssignment` | Gateway, runtime, and connector control plane | Freezes the context used for authorization, persistence, routing, and handler execution |\n\nParsing moves bytes into typed wire objects. It does not move a value from the\nfirst row to the second. Authentication, resolution, and authorization are\nseparate decisions, and each can fail independently.\n\nThis separation also prevents identity roles from collapsing into one value.\nThe transport actor can be a service while `human_actor` identifies the person\nwho initiated the work, `acted_on_behalf_of` identifies the represented\nprincipal, and `external_user` names the account-local user understood by a\nprovider.\n\n## Wire identity describes the requested context\n\n`Principal` is the canonical actor-shaped protocol object. Its `kind` is one of\n`human`, `agent`, `service`, `tenant`, `customer`, `contact`, or `system`.\n\n| Principal field | Meaning | Trust boundary |\n|---|---|---|\n| `id` and `kind` | Stable AIP identity and actor category | Must be bound to authenticated evidence before authorization |\n| `display_name` | Human-readable label | Never an authorization key |\n| `trust_domain` | Claimed owning domain | A label until the receiving deployment verifies the immediate peer |\n| `did` | Claimed decentralized identifier | Does not prove key possession by its presence |\n| `external_refs` | Product-local identity references | Require deployment or connector mapping before trusted use |\n| `delegated_authority` | Scoped grants for another principal's work | Authoritative only when retained on a transport-established principal |\n| `auth_context` | Profile or gateway authentication metadata | Its interpretation belongs to the trusted edge, not generic payload parsing |\n\n`IdentityContext` describes the identity and account mapping associated with an\naction or approval. It has eight optional fields:\n\n| Field | Intended meaning |\n|---|---|\n| `tenant` | Tenant or account isolation boundary |\n| `external_account` | Provider account selected for connector work |\n| `external_user` | Provider-local user associated with the invocation |\n| `human_actor` | Person who initiated or owns the intent |\n| `service_account` | Machine identity performing the operation |\n| `acted_on_behalf_of` | Principal whose authority is being exercised |\n| `credential_ref` | Identifier, issuer, and known scopes for material stored elsewhere |\n| `oauth` | Issuer, client identifier, scopes, expiry, and refresh availability without token material |\n\nThese fields are useful for routing, audit, policy, and provider mapping, but an\nincoming `Action.identity` is only a set of lookup hints.\n\nThe reviewed static resolver requires exact tenant and claimed-credential\nmatches. When its trusted\nidentity mapping contains account, user, human, or on-behalf-of values, it also\nrejects conflicting hints. A claim that is not present in the resolver result\nis discarded rather than copied into runtime state.\n\n## Authentication establishes the immediate actor\n\nThe runtime representation of a proven caller is `AuthenticatedPrincipal`. It\nretains the canonical principal together with the authentication scheme,\ntrusted issuer, optional audience, verified scopes, authentication time,\noptional expiry, and an optional non-secret token or certificate fingerprint.\nValidation rejects expired authentication and missing required scopes.\n\nThe authentication vocabulary contains `did_proof`, `bearer`, `oauth2`,\n`hmac_webhook`, `mtls`, and `api_key`. This enum is not an assurance that every\ntransport binding implements every scheme. Each network edge must verify its\nown token, certificate, webhook, or peer credential before calling the trusted\ngateway entrypoint.\n\nThe reviewed gateway has three relevant ingress patterns:\n\n1. Native signed ingress verifies the Ed25519 signature over the canonical\n   envelope, obtains a `did:key` verifier, looks up that DID in the trusted\n   signer map, and checks that `Envelope.from.id` and `kind` match the bound\n   principal.\n2. An already authenticated in-process edge supplies a principal, or supplies\n   a complete `AuthenticatedPrincipal` plus verified tenant and credential\n   state. The gateway overwrites any payload sender with that actor.\n3. An explicitly insecure local-development gateway may accept unsigned\n   payload identity. The constructor is documented as unsuitable for a\n   network-facing deployment.\n\nA valid native signature proves possession of the private key corresponding to\nthe returned DID. It does not, by itself, decide which principal owns that DID,\nwhich tenant the principal belongs to, which scopes are permitted, or whether\nthe requested capability is authorized. Those are separate trusted bindings\nand policy checks.\n\nThe gateway also applies its replay window independently from authentication.\nA correctly signed envelope can still be rejected as stale, too far in the\nfuture, or a replay of an already claimed message ID.\n\n## Trusted enrichment replaces caller claims\n\nIdentity resolution runs when an action carries identity hints or configured\nfleet routing needs identity for an unknown local capability. It also runs when\nthe gateway marks a capability as identity-required or the capability credential\npolicy requires a credential, issuer, or scope check. Delegated child actions\ncross the same resolution boundary as root actions.\n\nThe reviewed flow is:\n\n1. The gateway authenticates the transport actor and collects the capability's\n   accepted credential issuers and required credential scopes.\n2. It passes the actor and untrusted action identity to a\n   `TrustedIdentityResolver`.\n3. The resolver returns the same actor plus optional `VerifiedTenant`,\n   `CredentialHandle`, and sanitized `IdentityContext` values from\n   deployment-owned data.\n4. The gateway rejects actor replacement, actor-kind changes, scope elevation,\n   expired membership or credentials, tenant mismatch, an unacceptable issuer,\n   a missing required credential, and any mismatch between the sanitized\n   identity and its verified tenant or credential.\n5. The gateway stores only the validated values in `MessageContext`; the\n   runtime copies `context.resolved_identity` over `Action.identity` before\n   preflight, queueing, persistence, and handler execution.\n\nThe default resolver is deny-all when no trusted identity provider is\nconfigured. The daemon's static directory is a controlled-deployment adapter:\neach entry is keyed by an authenticated principal and may contain verified\ntenant, opaque credential, sanitized identity, monotonic revision, revocation,\nand expiry state. Its loader rejects an empty directory, duplicate principals,\nzero revisions, revoked entries, expired entries, expired tenant membership,\nand expired credential handles.\n\nAn optional cache wrapper remains revocation-aware by asking the underlying\nresolver for its current revision before reuse. The provided default cache\nbounds are 10,000 entries and five seconds, further shortened by actor, tenant,\nor credential expiry. A resolver that cannot return a revision bypasses this\ncache rather than extending an identity decision without a revocation signal.\n\n## Tenant and credential authority stay deployment-owned\n\n`VerifiedTenant` combines the canonical tenant reference with a membership ID,\nresolver-established roles and groups, verification time, and optional expiry.\nIt is distinct from the tenant claim in `Action.identity`. Tenant-scoped\nexecution and queries use the verified value.\n\n`CredentialHandle` is an opaque runtime reference. It contains an identifier,\nissuer, scopes, optional tenant partition, and optional expiry, with the\nidentifier redacted from its debug representation. The gateway checks required\nscopes and accepted issuers. If the handle names a tenant, verified tenant\nmembership must exist and match it.\n\nThe similarly shaped wire `CredentialRef` is a projection for protocol and\naudit context; it is not secret material and cannot be exchanged for authority\nwithout the trusted runtime handle. Capability contracts can require a\ncredential and constrain issuers and scopes, but the deployment decides how a\nhandle maps to a real provider credential.\n\n`CredentialProvider` is the final secret boundary. It resolves a handle into\nshort-lived `CredentialMaterial` for an immediate connector invocation. The\nprovided material type redacts debug output and overwrites its owned byte\nbuffer when dropped. Callers must still avoid copying those bytes into durable\nactions, errors, logs, receipts, traces, manifests, or connector route data.\n\n## Operational reads require ownership, tenant, and scope\n\nKnowing an action, session, approval, transaction, receipt, audit, callback,\nresource, or event identifier does not authorize access to it. The reviewed\nquery authorization service combines:\n\n- a non-expired authenticated actor;\n- object ownership or a trusted grant for the selected principal;\n- a verified tenant and matching tenant selector when the actor is\n  tenant-bound;\n- the exact object-specific read, write, or export scope;\n- additional operation-specific scopes; and\n- a separate sensitive-data scope before protected fields are disclosed.\n\nMissing ownership, tenant, or scope information is denied. When the base read\nis authorized but the sensitive-data scope is absent, the service returns a\nfield-disclosure decision that identifies fields to redact.\n\nA `DelegatedAuthorityGrant` identifies one principal whose work is covered,\nthe permitted scopes, an optional expiry, and an optional audit reason. The\nquery service accepts it only from the authenticated principal, for the exact\ntarget principal, while it is unexpired, and for the exact requested scope or\nthe wildcard `*`.\n\nThis is narrower than granting a global `object:read:any`\nscope. Delegation-chain continuity, hop limits, and remote delegation behavior\nare covered separately.\n\nApproval authority is also resolved independently. A requester, action\nsubject, and approver can be different principals; role or group text in an\napproval payload is not a substitute for trusted authority membership.\n\n## Connector fleets pin both principal and key identity\n\nA connector fleet introduces two machine identities at every remote execution\nedge: the central gateway that signs the request and the connector-host replica\nthat signs responses, callbacks, events, and lifecycle control messages.\n\nFor each replica, the registry stores the expected principal ID, principal\nkind, `peer_did`, trust domain, endpoint, immutable connector version, lease,\nand health revision. Route selection copies those values into a durable\n`RouteAssignment` together with the tenant, manifest digest, catalog and policy\nrevisions, credential revision, quota policy, and fencing token.\n\nThe central dispatcher signs the outbound envelope as its bound gateway\nprincipal and verifies the response against the route's expected host\nprincipal and DID. The connector host trusts one configured gateway principal\nand gateway DID, verifies the signed request, and resolves that gateway to the\nhost's fixed tenant, provider account, and opaque credential.\n\nConnector event and stream-callback ingress performs the reverse check:\nsignature DID, sender\nprincipal, trust domain, active replica lease, and durable route must agree.\n\nConnector control-plane requests are signed by the host DID, while the host\npins and verifies the control-plane DID in responses. A remote host receives a\nnarrow lifecycle surface rather than registry-administrator or database\ncredentials, and the replica identity is pre-provisioned before activation.\n\nThe connector manifest and the replica key have different lifecycles. The host\nrequires the manifest's semantic agent identity to match its signing principal,\nbut removes the replica DID from the published manifest. The trust domain stays\npart of the manifest identity; the per-replica DID remains in the registry.\nThis permits horizontal replicas and key rotation without changing the\nimmutable connector-version digest.\n\n## Credential revision is pinned separately from secret material\n\nA tenant capability binding can name an opaque `credential_revision_ref`.\nRoute assignment pins that reference before execution and carries it to the\nselected connector host. The host requires its credential handle and revision\nreference to be configured together and verifies the pinned revision against a\ndeployment-owned `CredentialRevisionProvider` before dispatching the request to\nits gateway and connector.\n\nThe provided policy distinguishes:\n\n| Revision set | Meaning |\n|---|---|\n| `current_revision_ref` | Revision assigned to new work |\n| `accepted_previous_revisions` | Older pinned work allowed during an explicit overlap window |\n| `revoked_revisions` | Revisions denied immediately, even if an earlier route pinned them |\n\nThe sets cannot overlap. Revocation wins, and an unavailable revision authority\nfails the request rather than guessing. The reference remains non-secret; it\ndoes not expose a token or prove that a provider accepted an operation.\n\n## Network and administrative surfaces stay bounded\n\nIdentity verification does not authorize an implementation to contact an\narbitrary issuer or provider URL supplied by a caller. The reviewed OAuth\nintrospection client uses a deployment-configured HTTPS endpoint, disables\nredirects, applies a five-second timeout, and limits the response body to one\nMiB. Its explicit HTTP exception accepts loopback destinations only for local\ndevelopment.\n\nConnector-host control and message clients likewise use fixed deployment or\nregistry destinations with transport, redirect, time, and body constraints.\nExact values belong to their configuration and security reference pages rather\nthan this identity model.\n\nThese trust paths do not expose general identity, registry, or credential\nadministration. The remote connector host receives only registration,\nheartbeat, drain, and offline lifecycle operations; it does not receive a\nregistry-administrator or direct database credential. Credential issuance,\nsecret storage, OAuth consent, and provider-account administration remain\noutside the AIP wire surface.\n\n## Trust and data boundaries\n\n- Payload `from`, `did`, `trust_domain`, delegated grants, tenant, account,\n  user, and credential references remain untrusted until the appropriate edge\n  or resolver establishes them.\n- Authentication proves an immediate actor under one issuer and audience. It\n  does not automatically grant capability, tenant, object, approval, or\n  provider authority.\n- Trusted enrichment may use payload values only as lookup hints. A mismatch is\n  an authorization failure, not a reason to copy the claim into runtime state.\n- Tenant membership, downstream credentials, and approval memberships have\n  independent expiry and revocation lifecycles.\n- Raw provider secrets stay behind the credential-provider boundary. Opaque\n  handles and revision references may be persisted; secret bytes may not.\n- A DID key proves signature possession. Principal ownership, trust domain,\n  active connector lease, durable route, and policy must also match.\n- Each federation or delegation hop authenticates its immediate peer and\n  applies local policy. A trust-domain label does not create transitive trust.\n- Audit identity can be sensitive. Retention, redaction, and sensitive-field\n  disclosure remain deployment policy even when an operation is authorized.\n\n## Design choices and trade-offs\n\nKeeping `Principal` and `IdentityContext` on the wire preserves product and\nhuman context across transports and compatibility profiles. Treating them as\nclaims requires an explicit resolver, but prevents a caller from selecting its\nown tenant, credential, or on-behalf-of authority.\n\nSeparating authentication from authorization lets a deployment use DID\nsignatures, tokens, mTLS, webhooks, or authenticated adapters without changing\nthe semantic action model. The cost is that every edge must clearly own its\nverification contract; merely selecting an `AuthScheme` enum is insufficient.\n\nOpaque credential handles and revisions keep secret bytes out of durable AIP\nrecords and allow controlled overlap during rotation. They add a final online\nauthorization check, and a revocation-service outage can deliberately block\nprovider work.\n\nSeparating manifest identity from replica DID keeps connector artifacts stable\nacross scaling and key rotation. The registry and route assignment must then\nretain exact per-replica identity, lease, and revision evidence.\n\nRevision-aware caching improves resolver latency while preserving a fast\nrevocation signal. Resolvers without that signal give up caching rather than\nsilently extending trust.\n\n## What this model does not guarantee\n\n- A well-formed `Principal` or `IdentityContext` is not authenticated.\n- A valid signature is not authorization and does not establish tenant\n  membership by itself.\n- The authentication-scheme enum does not promise support for every scheme on\n  every binding or deployment.\n- A static identity directory is not a complete production IAM system.\n- A credential reference or revision is not secret material and cannot prove\n  that a provider credential is live.\n- Memory zeroing of the owned credential buffer cannot erase copies made by\n  other libraries, operating systems, or external providers.\n- A trust domain does not imply universal or transitive federation.\n- Scoped authorization does not prove connector qualification, provider\n  correctness, or exactly-once external side effects.\n- This page does not publish connectors beyond Cal.diy, Hermes Agent, Chatwoot,\n  Dify, CrewAI, and Twenty.\n\n## Related pages\n\n- [Approvals and policy](approvals-and-policy.md)\n- [Delegation](delegation.md)\n- [Profiles and connectors](profiles-and-connectors.md)\n- [Security model](../architecture/security-model.md)\n- [Connector credentials and rotation](../guides/connector-credentials-and-rotation.md)\n",
    "text": "Identity and trust\n\nUse this page to decide which identity values an AIP implementation may trust.\nIt covers caller authentication, tenant and provider-account selection,\ncredential resolution, operational reads, and connector dispatch. It is for\ngateway, runtime, connector, and platform developers.\n\nThe central rule is simple: identity carried in an AIP payload is a claim, not\nproof. A production path first establishes an actor at a transport or signature\nedge, then enriches that actor from deployment-owned data. The runtime executes\nwith the enriched context and replaces caller-supplied action identity before a\nhandler sees the action.\n\nThis page describes the reviewed Rust implementation of AIP 1.0 at source\nrevision 97be86e9efedf07ecf1783b03800f683f107fb04. A deployment still owns its\nidentity provider, issuer trust, tenant directory, credential store, key\nlifecycle, and policy. The implementation exposes primitives for those\nboundaries; it does not create a universal identity federation.\n\nKeep four identity layers separate\n\n| Layer | Main type or record | Authority | Purpose |\n\n| Wire claim | Principal, Envelope.from, and Action.identity | Caller-controlled until verified | Names actors and supplies identity lookup hints |\n| Authenticated actor | AuthenticatedPrincipal | Transport authenticator or trusted DID binding | Records the proven principal, scheme, issuer, scopes, time, expiry, and optional credential fingerprint |\n| Trusted enrichment | ResolvedIdentity | Deployment-owned identity resolver | Adds verified tenant membership, an opaque credential handle, and sanitized product identity |\n| Execution boundary | MessageContext and, for fleets, RouteAssignment | Gateway, runtime, and connector control plane | Freezes the context used for authorization, persistence, routing, and handler execution |\n\nParsing moves bytes into typed wire objects. It does not move a value from the\nfirst row to the second. Authentication, resolution, and authorization are\nseparate decisions, and each can fail independently.\n\nThis separation also prevents identity roles from collapsing into one value.\nThe transport actor can be a service while humanactor identifies the person\nwho initiated the work, actedonbehalfof identifies the represented\nprincipal, and externaluser names the account-local user understood by a\nprovider.\n\nWire identity describes the requested context\n\nPrincipal is the canonical actor-shaped protocol object. Its kind is one of\nhuman, agent, service, tenant, customer, contact, or system.\n\n| Principal field | Meaning | Trust boundary |\n\n| id and kind | Stable AIP identity and actor category | Must be bound to authenticated evidence before authorization |\n| displayname | Human-readable label | Never an authorization key |\n| trustdomain | Claimed owning domain | A label until the receiving deployment verifies the immediate peer |\n| did | Claimed decentralized identifier | Does not prove key possession by its presence |\n| externalrefs | Product-local identity references | Require deployment or connector mapping before trusted use |\n| delegatedauthority | Scoped grants for another principal's work | Authoritative only when retained on a transport-established principal |\n| authcontext | Profile or gateway authentication metadata | Its interpretation belongs to the trusted edge, not generic payload parsing |\n\nIdentityContext describes the identity and account mapping associated with an\naction or approval. It has eight optional fields:\n\n| Field | Intended meaning |\n\n| tenant | Tenant or account isolation boundary |\n| externalaccount | Provider account selected for connector work |\n| externaluser | Provider-local user associated with the invocation |\n| humanactor | Person who initiated or owns the intent |\n| serviceaccount | Machine identity performing the operation |\n| actedonbehalfof | Principal whose authority is being exercised |\n| credentialref | Identifier, issuer, and known scopes for material stored elsewhere |\n| oauth | Issuer, client identifier, scopes, expiry, and refresh availability without token material |\n\nThese fields are useful for routing, audit, policy, and provider mapping, but an\nincoming Action.identity is only a set of lookup hints.\n\nThe reviewed static resolver requires exact tenant and claimed-credential\nmatches. When its trusted\nidentity mapping contains account, user, human, or on-behalf-of values, it also\nrejects conflicting hints. A claim that is not present in the resolver result\nis discarded rather than copied into runtime state.\n\nAuthentication establishes the immediate actor\n\nThe runtime representation of a proven caller is AuthenticatedPrincipal. It\nretains the canonical principal together with the authentication scheme,\ntrusted issuer, optional audience, verified scopes, authentication time,\noptional expiry, and an optional non-secret token or certificate fingerprint.\nValidation rejects expired authentication and missing required scopes.\n\nThe authentication vocabulary contains didproof, bearer, oauth2,\nhmacwebhook, mtls, and apikey. This enum is not an assurance that every\ntransport binding implements every scheme. Each network edge must verify its\nown token, certificate, webhook, or peer credential before calling the trusted\ngateway entrypoint.\n\nThe reviewed gateway has three relevant ingress patterns:\n1. Native signed ingress verifies the Ed25519 signature over the canonical\n   envelope, obtains a did:key verifier, looks up that DID in the trusted\n   signer map, and checks that Envelope.from.id and kind match the bound\n   principal.\n2. An already authenticated in-process edge supplies a principal, or supplies\n   a complete AuthenticatedPrincipal plus verified tenant and credential\n   state. The gateway overwrites any payload sender with that actor.\n3. An explicitly insecure local-development gateway may accept unsigned\n   payload identity. The constructor is documented as unsuitable for a\n   network-facing deployment.\n\nA valid native signature proves possession of the private key corresponding to\nthe returned DID. It does not, by itself, decide which principal owns that DID,\nwhich tenant the principal belongs to, which scopes are permitted, or whether\nthe requested capability is authorized. Those are separate trusted bindings\nand policy checks.\n\nThe gateway also applies its replay window independently from authentication.\nA correctly signed envelope can still be rejected as stale, too far in the\nfuture, or a replay of an already claimed message ID.\n\nTrusted enrichment replaces caller claims\n\nIdentity resolution runs when an action carries identity hints or configured\nfleet routing needs identity for an unknown local capability. It also runs when\nthe gateway marks a capability as identity-required or the capability credential\npolicy requires a credential, issuer, or scope check. Delegated child actions\ncross the same resolution boundary as root actions.\n\nThe reviewed flow is:\n1. The gateway authenticates the transport actor and collects the capability's\n   accepted credential issuers and required credential scopes.\n2. It passes the actor and untrusted action identity to a\n   TrustedIdentityResolver.\n3. The resolver returns the same actor plus optional VerifiedTenant,\n   CredentialHandle, and sanitized IdentityContext values from\n   deployment-owned data.\n4. The gateway rejects actor replacement, actor-kind changes, scope elevation,\n   expired membership or credentials, tenant mismatch, an unacceptable issuer,\n   a missing required credential, and any mismatch between the sanitized\n   identity and its verified tenant or credential.\n5. The gateway stores only the validated values in MessageContext; the\n   runtime copies context.resolvedidentity over Action.identity before\n   preflight, queueing, persistence, and handler execution.\n\nThe default resolver is deny-all when no trusted identity provider is\nconfigured. The daemon's static directory is a controlled-deployment adapter:\neach entry is keyed by an authenticated principal and may contain verified\ntenant, opaque credential, sanitized identity, monotonic revision, revocation,\nand expiry state. Its loader rejects an empty directory, duplicate principals,\nzero revisions, revoked entries, expired entries, expired tenant membership,\nand expired credential handles.\n\nAn optional cache wrapper remains revocation-aware by asking the underlying\nresolver for its current revision before reuse. The provided default cache\nbounds are 10,000 entries and five seconds, further shortened by actor, tenant,\nor credential expiry. A resolver that cannot return a revision bypasses this\ncache rather than extending an identity decision without a revocation signal.\n\nTenant and credential authority stay deployment-owned\n\nVerifiedTenant combines the canonical tenant reference with a membership ID,\nresolver-established roles and groups, verification time, and optional expiry.\nIt is distinct from the tenant claim in Action.identity. Tenant-scoped\nexecution and queries use the verified value.\n\nCredentialHandle is an opaque runtime reference. It contains an identifier,\nissuer, scopes, optional tenant partition, and optional expiry, with the\nidentifier redacted from its debug representation. The gateway checks required\nscopes and accepted issuers. If the handle names a tenant, verified tenant\nmembership must exist and match it.\n\nThe similarly shaped wire CredentialRef is a projection for protocol and\naudit context; it is not secret material and cannot be exchanged for authority\nwithout the trusted runtime handle. Capability contracts can require a\ncredential and constrain issuers and scopes, but the deployment decides how a\nhandle maps to a real provider credential.\n\nCredentialProvider is the final secret boundary. It resolves a handle into\nshort-lived CredentialMaterial for an immediate connector invocation. The\nprovided material type redacts debug output and overwrites its owned byte\nbuffer when dropped. Callers must still avoid copying those bytes into durable\nactions, errors, logs, receipts, traces, manifests, or connector route data.\n\nOperational reads require ownership, tenant, and scope\n\nKnowing an action, session, approval, transaction, receipt, audit, callback,\nresource, or event identifier does not authorize access to it. The reviewed\nquery authorization service combines:\n• a non-expired authenticated actor;\n• object ownership or a trusted grant for the selected principal;\n• a verified tenant and matching tenant selector when the actor is\n  tenant-bound;\n• the exact object-specific read, write, or export scope;\n• additional operation-specific scopes; and\n• a separate sensitive-data scope before protected fields are disclosed.\n\nMissing ownership, tenant, or scope information is denied. When the base read\nis authorized but the sensitive-data scope is absent, the service returns a\nfield-disclosure decision that identifies fields to redact.\n\nA DelegatedAuthorityGrant identifies one principal whose work is covered,\nthe permitted scopes, an optional expiry, and an optional audit reason. The\nquery service accepts it only from the authenticated principal, for the exact\ntarget principal, while it is unexpired, and for the exact requested scope or\nthe wildcard .\n\nThis is narrower than granting a global object:read:any\nscope. Delegation-chain continuity, hop limits, and remote delegation behavior\nare covered separately.\n\nApproval authority is also resolved independently. A requester, action\nsubject, and approver can be different principals; role or group text in an\napproval payload is not a substitute for trusted authority membership.\n\nConnector fleets pin both principal and key identity\n\nA connector fleet introduces two machine identities at every remote execution\nedge: the central gateway that signs the request and the connector-host replica\nthat signs responses, callbacks, events, and lifecycle control messages.\n\nFor each replica, the registry stores the expected principal ID, principal\nkind, peerdid, trust domain, endpoint, immutable connector version, lease,\nand health revision. Route selection copies those values into a durable\nRouteAssignment together with the tenant, manifest digest, catalog and policy\nrevisions, credential revision, quota policy, and fencing token.\n\nThe central dispatcher signs the outbound envelope as its bound gateway\nprincipal and verifies the response against the route's expected host\nprincipal and DID. The connector host trusts one configured gateway principal\nand gateway DID, verifies the signed request, and resolves that gateway to the\nhost's fixed tenant, provider account, and opaque credential.\n\nConnector event and stream-callback ingress performs the reverse check:\nsignature DID, sender\nprincipal, trust domain, active replica lease, and durable route must agree.\n\nConnector control-plane requests are signed by the host DID, while the host\npins and verifies the control-plane DID in responses. A remote host receives a\nnarrow lifecycle surface rather than registry-administrator or database\ncredentials, and the replica identity is pre-provisioned before activation.\n\nThe connector manifest and the replica key have different lifecycles. The host\nrequires the manifest's semantic agent identity to match its signing principal,\nbut removes the replica DID from the published manifest. The trust domain stays\npart of the manifest identity; the per-replica DID remains in the registry.\nThis permits horizontal replicas and key rotation without changing the\nimmutable connector-version digest.\n\nCredential revision is pinned separately from secret material\n\nA tenant capability binding can name an opaque credentialrevisionref.\nRoute assignment pins that reference before execution and carries it to the\nselected connector host. The host requires its credential handle and revision\nreference to be configured together and verifies the pinned revision against a\ndeployment-owned CredentialRevisionProvider before dispatching the request to\nits gateway and connector.\n\nThe provided policy distinguishes:\n\n| Revision set | Meaning |\n\n| currentrevisionref | Revision assigned to new work |\n| acceptedpreviousrevisions | Older pinned work allowed during an explicit overlap window |\n| revokedrevisions | Revisions denied immediately, even if an earlier route pinned them |\n\nThe sets cannot overlap. Revocation wins, and an unavailable revision authority\nfails the request rather than guessing. The reference remains non-secret; it\ndoes not expose a token or prove that a provider accepted an operation.\n\nNetwork and administrative surfaces stay bounded\n\nIdentity verification does not authorize an implementation to contact an\narbitrary issuer or provider URL supplied by a caller. The reviewed OAuth\nintrospection client uses a deployment-configured HTTPS endpoint, disables\nredirects, applies a five-second timeout, and limits the response body to one\nMiB. Its explicit HTTP exception accepts loopback destinations only for local\ndevelopment.\n\nConnector-host control and message clients likewise use fixed deployment or\nregistry destinations with transport, redirect, time, and body constraints.\nExact values belong to their configuration and security reference pages rather\nthan this identity model.\n\nThese trust paths do not expose general identity, registry, or credential\nadministration. The remote connector host receives only registration,\nheartbeat, drain, and offline lifecycle operations; it does not receive a\nregistry-administrator or direct database credential. Credential issuance,\nsecret storage, OAuth consent, and provider-account administration remain\noutside the AIP wire surface.\n\nTrust and data boundaries\n• Payload from, did, trustdomain, delegated grants, tenant, account,\n  user, and credential references remain untrusted until the appropriate edge\n  or resolver establishes them.\n• Authentication proves an immediate actor under one issuer and audience. It\n  does not automatically grant capability, tenant, object, approval, or\n  provider authority.\n• Trusted enrichment may use payload values only as lookup hints. A mismatch is\n  an authorization failure, not a reason to copy the claim into runtime state.\n• Tenant membership, downstream credentials, and approval memberships have\n  independent expiry and revocation lifecycles.\n• Raw provider secrets stay behind the credential-provider boundary. Opaque\n  handles and revision references may be persisted; secret bytes may not.\n• A DID key proves signature possession. Principal ownership, trust domain,\n  active connector lease, durable route, and policy must also match.\n• Each federation or delegation hop authenticates its immediate peer and\n  applies local policy. A trust-domain label does not create transitive trust.\n• Audit identity can be sensitive. Retention, redaction, and sensitive-field\n  disclosure remain deployment policy even when an operation is authorized.\n\nDesign choices and trade-offs\n\nKeeping Principal and IdentityContext on the wire preserves product and\nhuman context across transports and compatibility profiles. Treating them as\nclaims requires an explicit resolver, but prevents a caller from selecting its\nown tenant, credential, or on-behalf-of authority.\n\nSeparating authentication from authorization lets a deployment use DID\nsignatures, tokens, mTLS, webhooks, or authenticated adapters without changing\nthe semantic action model. The cost is that every edge must clearly own its\nverification contract; merely selecting an AuthScheme enum is insufficient.\n\nOpaque credential handles and revisions keep secret bytes out of durable AIP\nrecords and allow controlled overlap during rotation. They add a final online\nauthorization check, and a revocation-service outage can deliberately block\nprovider work.\n\nSeparating manifest identity from replica DID keeps connector artifacts stable\nacross scaling and key rotation. The registry and route assignment must then\nretain exact per-replica identity, lease, and revision evidence.\n\nRevision-aware caching improves resolver latency while preserving a fast\nrevocation signal. Resolvers without that signal give up caching rather than\nsilently extending trust.\n\nWhat this model does not guarantee\n• A well-formed Principal or IdentityContext is not authenticated.\n• A valid signature is not authorization and does not establish tenant\n  membership by itself.\n• The authentication-scheme enum does not promise support for every scheme on\n  every binding or deployment.\n• A static identity directory is not a complete production IAM system.\n• A credential reference or revision is not secret material and cannot prove\n  that a provider credential is live.\n• Memory zeroing of the owned credential buffer cannot erase copies made by\n  other libraries, operating systems, or external providers.\n• A trust domain does not imply universal or transitive federation.\n• Scoped authorization does not prove connector qualification, provider\n  correctness, or exactly-once external side effects.\n• This page does not publish connectors beyond Cal.diy, Hermes Agent, Chatwoot,\n  Dify, CrewAI, and Twenty.\n\nRelated pages\n• Approvals and policy (approvals-and-policy.md)\n• Delegation (delegation.md)\n• Profiles and connectors (profiles-and-connectors.md)\n• Security model (../architecture/security-model.md)\n• Connector credentials and rotation (../guides/connector-credentials-and-rotation.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "388e585b048e7d9b4581567573a5c39752a3928c997eebf4ef8db55900849be5"
  }
}