{
  "schemaVersion": "1.0",
  "title": "Authenticate and bind Hermes endpoints",
  "description": "Use this guide to bind one or more owner-configured Hermes API servers to one AIP tenant. Each endpoint receives a stable ID, a fixed base URL, and its own owner-only APISERVERKEY file. The connector then publishes endpoint-qualified capabi",
  "canonical": "https://getaip.org/docs/connectors/hermes-agent/getting-started/authentication-and-endpoints",
  "route": "/docs/connectors/hermes-agent/getting-started/authentication-and-endpoints",
  "source": "docs/connectors/hermes-agent/getting-started/authentication-and-endpoints.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/hermes-agent/getting-started/authentication-and-endpoints.md",
    "txt": "/docs/download/connectors/hermes-agent/getting-started/authentication-and-endpoints.txt",
    "json": "/docs/download/connectors/hermes-agent/getting-started/authentication-and-endpoints.json",
    "pdf": "/docs/download/connectors/hermes-agent/getting-started/authentication-and-endpoints.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Authenticate and bind Hermes endpoints\ndescription: >-\n  Bind tenant-owned Hermes API servers to one standalone connector host and\n  rotate their Bearer tokens safely\nkind: how-to\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: hermes-agent\n---\n\n# Authenticate and bind Hermes endpoints\n\nUse this guide to bind one or more owner-configured Hermes API servers to one\nAIP tenant. Each endpoint receives a stable ID, a fixed base URL, and its own\nowner-only `API_SERVER_KEY` file. The connector then publishes endpoint-qualified\ncapabilities and adds the matching Bearer token inside the host process.\n\nThe endpoint is selected by the admitted capability ID, never by action input.\nA caller cannot supply a different URL, token, or tenant at invocation time.\n\n## Keep the credential layers separate\n\nFive related values protect different boundaries. Do not reuse one value for\nanother layer.\n\n| Layer | Protects | Configured for | Secret |\n|---|---|---|---|\n| Caller credential | Application to `aipd` | Native HTTP or signed-native client | Yes |\n| Gateway signature | `aipd` to connector host | Pinned gateway DID and trust domain | Private signing material stays with the gateway |\n| Host credential revision | Route authorization before provider work | Opaque handle, scopes, revision, and revision policy | No provider secret bytes |\n| Hermes endpoint token | Connector host to one Hermes API server | Endpoint `api_key_file`; sent as Bearer auth | Yes |\n| Model-provider credential | Hermes to its configured model provider | Hermes deployment | Yes; never supplied to AIP |\n\n`AIPCTL_NATIVE_BEARER_TOKEN_FILE` authenticates the caller to `aipd`. It must\nnot point to a Hermes endpoint token. Likewise, the host credential revision\nfences which admitted route may perform provider work; it does not load or\nreplace `API_SERVER_KEY`.\n\n## Prerequisites\n\nBefore changing an endpoint set, require:\n\n- one approved AIP tenant and standalone Hermes connector instance;\n- one owner-controlled Hermes API server per endpoint;\n- a valid `API_SERVER_KEY` for every protected endpoint;\n- an HTTPS service identity or a controlled local-network exception;\n- owner-controlled regular files for endpoint descriptors and tokens;\n- the common host identity, gateway trust, database, admission, and credential\n  revision inputs described in the connector-host reference;\n- a signed admission package for the exact manifest produced by the endpoint\n  set;\n- a non-mutating Hermes read and access to provider audit evidence.\n\nChanging endpoint IDs, URLs, tenant values, or membership changes the connector\nmanifest. Plan a new immutable connector version and admission package before\nmaking any of those changes. The current manifest does not project\n`display_name` or token bytes.\n\n## 1. Choose the endpoint and tenant boundary\n\nGive each endpoint a stable operational ID. The host trims surrounding\nwhitespace, accepts only ASCII letters, digits, hyphens, and underscores, and\nnormalizes the result to lowercase.\n\nFor example, `Primary_US` becomes `primary_us`. Two configured values that\nnormalize to the same ID make startup fail. Do not encode a rotating token,\nreplica name, or mutable deployment timestamp in the ID.\n\nEvery endpoint in one standalone host belongs to the host's exact\n`AIP_CONNECTOR_HOST_TENANT_ID`. An omitted descriptor `tenant_id` inherits that\nvalue. An explicit different value fails startup, and every invocation fails\nclosed unless the trusted runtime tenant matches the endpoint tenant.\n\nUse separate connector instances for different tenants. `display_name` is\nretained in endpoint configuration at this revision, but it does not affect\nrouting, capability names, or the discovered manifest.\n\n## 2. Provision one token file per endpoint\n\nCreate the token through the owner-approved Hermes process and configure the\nsame value as `API_SERVER_KEY` on that Hermes API server. Store only the\nconnector-side copy in a dedicated file, for example:\n\n```text\n/run/secrets/hermes-primary-api-key\n```\n\nThe connector accepts a non-empty UTF-8 value of at most 16 KiB after trimming\nleading and trailing ASCII whitespace. On Unix, the path must be a regular\nnon-symlink file with no group or world permission bits. A typical mounted-file\nmode is `0600`.\n\nKeep these invariants:\n\n- one endpoint token file identifies one Hermes authentication boundary;\n- the file is mounted read-only into only the replicas that need it;\n- the token never appears in descriptor JSON, action input, admission data,\n  logs, shell history, or a source repository;\n- the file path may be recorded, but its bytes may not be printed as evidence;\n- model-provider, MCP, and webhook credentials remain outside this file.\n\nThe connector excludes token bytes from serialized endpoint configuration and\nredacts its endpoint collection in debug output. Deployment logging and secret\nmount policy must preserve that boundary too.\n\n## 3. Write the endpoint descriptor file\n\nCreate a bounded JSON array in an owner-controlled configuration file:\n\n```json\n[\n  {\n    \"id\": \"primary\",\n    \"base_url\": \"https://hermes-primary.example.internal:8642\",\n    \"api_key_file\": \"/run/secrets/hermes-primary-api-key\",\n    \"display_name\": \"Primary Hermes\",\n    \"tenant_id\": \"tenant-acme\"\n  }\n]\n```\n\nPoint `AIP_HERMES_ENDPOINTS_FILE` at this file. Each object has two required\nfields and three optional fields:\n\n| Field | Required | Meaning |\n|---|---:|---|\n| `id` | Yes | Stable endpoint segment in every generated capability ID |\n| `base_url` | Yes | Owner-selected Hermes API-server origin |\n| `api_key_file` | No | File containing the endpoint Bearer token |\n| `display_name` | No | Human-readable label; never a routing key |\n| `tenant_id` | No | Explicit tenant assertion; otherwise inherits the host tenant |\n\nUnknown fields are rejected. The descriptor file must be a regular\nnon-symlink JSON file of 1 byte through 4 MiB. On Unix it may be group- or\nworld-readable, but it must not be group- or world-writable. It is non-secret\nonly because it contains file references rather than token bytes.\n\nThe parser accepts 1 through 1000 descriptors. That is not the deployable\nlimit. Each endpoint creates 35 capabilities, while the current standalone\nhost accepts at most 512. The effective manifest limit is therefore 14\nendpoints: 14 produce 490 capabilities, while 15 produce 525 and fail host\npreparation. This is a source limit, not a scale qualification.\n\n## 4. Validate endpoint identities and destinations\n\nReview the descriptor set before admission:\n\n1. Normalize every endpoint ID and reject collisions.\n2. Confirm that every explicit tenant equals the host tenant exactly.\n3. Confirm that every URL parses with the `http` or `https` scheme.\n4. Resolve each URL through owner-controlled service discovery.\n5. Confirm that every token file belongs to the intended endpoint.\n6. Count `35 × endpoints` and keep the result at or below 512.\n\nThe connector accepts both HTTP and HTTPS but does not prove destination\nownership. Use HTTPS outside a controlled loopback or private test network.\nThe default client follows no redirects, so a Hermes response cannot forward\nthe Bearer token to another origin. It uses a 10-second connection timeout and\na 900-second client timeout; individual operations can impose narrower bounds.\n\nRecord the resolved service identity privately. Do not add a caller-controlled\nproxy, URL suffix, or method to action input.\n\n## 5. Bind host trust and credential revision\n\nConfigure the standalone host's common identity and trust inputs independently\nfrom the endpoint file. At minimum, the admitted record and running host must\nagree on:\n\n- connector type, immutable version, instance, and replica IDs;\n- tenant and optional external-account identity;\n- public endpoint, host signing identity, and artifact digest;\n- central gateway principal, DID, and trust domain;\n- opaque credential ID, issuer, verified scopes, and revision reference;\n- credential-revision policy;\n- durable database and control-plane membership.\n\nThe host validates the route-pinned credential revision immediately before\ndispatching provider work. A revision-policy change can therefore stop an old\nroute without changing the Hermes token. Conversely, replacing a Hermes token\ndoes not authorize a different route revision.\n\nUse the shared connector-host configuration reference for exact fields and\nbounds. Keep this page's endpoint descriptor focused on Hermes only.\n\n## 6. Start through an admitted deployment\n\nGenerate the manifest from the exact endpoint set, artifact, and host\nconfiguration that will run. Admission must bind that immutable manifest to\nthe intended tenant-owned connector version before the replica becomes\ndiscoverable.\n\nStart the host with the descriptor and secret files already mounted. Startup\nmust fail if:\n\n- the array is empty, oversized, or invalid JSON;\n- an object has an unknown field;\n- an endpoint ID is invalid or duplicated after normalization;\n- a URL is invalid or uses another scheme;\n- a token file is missing, unsafe, empty, invalid UTF-8, or oversized;\n- an explicit endpoint tenant differs from the host tenant;\n- 35 capabilities per endpoint exceed the host manifest ceiling;\n- the common trust, storage, admission, or credential-revision checks fail.\n\nDo not bypass one of these failures by launching the product connector inside\n`aipd` or by admitting a manifest from a different descriptor set.\n\n## 7. Verify selection and authenticated access\n\nUse an already configured signed-native client context. Set the exact tenant\ngateway URL and normalized endpoint ID:\n\n```sh\nexport AIP_URL=https://aip.example\nexport HERMES_ENDPOINT_ID=primary\n```\n\nFirst require the endpoint-qualified protected capability in the tenant\ncatalog:\n\n```sh\naipctl capability list \"$AIP_URL\" \\\n  --signed-native \\\n  --capability-id \"cap:hermes_agent:${HERMES_ENDPOINT_ID}:models\"\n```\n\nExpected result: the bounded catalog page contains exactly the requested\ncapability for the admitted Hermes version. A catalog result proves routing\nmetadata, not token validity.\n\nBasic health is deliberately unauthenticated and cannot prove the endpoint\ntoken. Call the protected models read instead:\n\n```sh\naipctl action call \\\n  \"$AIP_URL\" \\\n  \"cap:hermes_agent:${HERMES_ENDPOINT_ID}:models\" \\\n  --action-id act_hermes_endpoint_auth_001 \\\n  --input '{}'\n```\n\nExpected result: the action reaches a terminal completed state and returns the\nHermes model catalog. Correlate the action ID, connector version, instance,\nreplica, endpoint ID, tenant, and provider audit record without retaining the\nBearer token.\n\nA completed protected read demonstrates that the selected endpoint possessed\na usable token at that time. It does not prove that every model-provider\ncredential, mutation, stream, operator policy, or delegation path works.\n\n## 8. Rotate an endpoint token\n\nThe standalone binary reads each API-key file once during startup. Replacing\nthe mounted file alone does not update a running process.\n\nFor a routine rotation:\n\n1. Create a new Hermes token and a new immutable connector-side secret file.\n2. Keep the old token valid while replacement replicas start.\n3. Start new replicas with the same admitted endpoint manifest and new token\n   bytes, using new replica identities.\n4. Require host readiness and repeat the protected `models` read through a\n   controlled route.\n5. Stop new assignments to old replicas and let their pinned actions settle.\n6. Drain and take the old replicas offline.\n7. Revoke the old Hermes token.\n8. Retain secret-free action, host, registry, and provider evidence.\n\nThe endpoint manifest need not change when only secret bytes change. The\nprocess still must be replaced or restarted so it loads the new bytes. If the\ncredential revision also changes, use the full blue/green instance procedure\nand preserve old pinned assignments under their original revision.\n\nFor a suspected compromise, first stop new routing and revoke the affected\nrevision or token according to the incident boundary. Do not prioritize a\ngraceful overlap over containment.\n\n## Resolve authentication and endpoint failures\n\n| Symptom | Likely boundary | Safe decision |\n|---|---|---|\n| Host rejects descriptor JSON | Shape, size, unknown field, or file permissions | Correct the owner-controlled file; do not relax parsing |\n| Duplicate endpoint error | IDs collide after trimming and lowercase normalization | Assign distinct stable IDs and create a new manifest |\n| Tenant mismatch at startup | Descriptor tenant differs from host tenant | Move the endpoint to the correct tenant instance |\n| `connector.hermes_agent.tenant_mismatch` | Trusted runtime tenant is absent or different | Repair admission and routing; never override tenant in input |\n| `connector.hermes_agent.missing_credential` | Protected operation has no usable endpoint key | Mount the correct owner-only file and replace the process |\n| Provider returns `401` or `403` | Token is invalid, revoked, or insufficient | Check the exact endpoint and provider audit; rotate or scope correctly |\n| Basic health passes but models fails | `/health` does not require endpoint auth | Diagnose the protected credential path; do not accept health as proof |\n| Catalog lacks the endpoint capability | Admitted manifest or binding differs | Reconcile version, instance, binding, and endpoint set |\n| Old token remains in use after file replacement | Running process retained startup bytes | Replace or restart the affected replica safely |\n| Request tries another origin after redirect | Provider returned redirect | Correct the configured base URL; redirects remain disabled |\n\nDo not retry a state-changing action merely because an authentication or\ntransport error appears retryable. Preserve the original action ID and use the\noperation-specific reconciliation guidance.\n\n## Related documentation\n\n- [Hermes Agent connector](../README.md)\n- [Hermes Agent quickstart](quickstart.md)\n- [Rotate connector credentials](../../../guides/connector-credentials-and-rotation.md)\n- [Connector registry and routing](../../../architecture/connector-registry-and-routing.md)\n- [Security model](../../../architecture/security-model.md)\n",
    "text": "Authenticate and bind Hermes endpoints\n\nUse this guide to bind one or more owner-configured Hermes API servers to one\nAIP tenant. Each endpoint receives a stable ID, a fixed base URL, and its own\nowner-only APISERVERKEY file. The connector then publishes endpoint-qualified\ncapabilities and adds the matching Bearer token inside the host process.\n\nThe endpoint is selected by the admitted capability ID, never by action input.\nA caller cannot supply a different URL, token, or tenant at invocation time.\n\nKeep the credential layers separate\n\nFive related values protect different boundaries. Do not reuse one value for\nanother layer.\n\n| Layer | Protects | Configured for | Secret |\n\n| Caller credential | Application to aipd | Native HTTP or signed-native client | Yes |\n| Gateway signature | aipd to connector host | Pinned gateway DID and trust domain | Private signing material stays with the gateway |\n| Host credential revision | Route authorization before provider work | Opaque handle, scopes, revision, and revision policy | No provider secret bytes |\n| Hermes endpoint token | Connector host to one Hermes API server | Endpoint apikeyfile; sent as Bearer auth | Yes |\n| Model-provider credential | Hermes to its configured model provider | Hermes deployment | Yes; never supplied to AIP |\n\nAIPCTLNATIVEBEARERTOKENFILE authenticates the caller to aipd. It must\nnot point to a Hermes endpoint token. Likewise, the host credential revision\nfences which admitted route may perform provider work; it does not load or\nreplace APISERVERKEY.\n\nPrerequisites\n\nBefore changing an endpoint set, require:\n• one approved AIP tenant and standalone Hermes connector instance;\n• one owner-controlled Hermes API server per endpoint;\n• a valid APISERVERKEY for every protected endpoint;\n• an HTTPS service identity or a controlled local-network exception;\n• owner-controlled regular files for endpoint descriptors and tokens;\n• the common host identity, gateway trust, database, admission, and credential\n  revision inputs described in the connector-host reference;\n• a signed admission package for the exact manifest produced by the endpoint\n  set;\n• a non-mutating Hermes read and access to provider audit evidence.\n\nChanging endpoint IDs, URLs, tenant values, or membership changes the connector\nmanifest. Plan a new immutable connector version and admission package before\nmaking any of those changes. The current manifest does not project\ndisplayname or token bytes.\n1. Choose the endpoint and tenant boundary\n\nGive each endpoint a stable operational ID. The host trims surrounding\nwhitespace, accepts only ASCII letters, digits, hyphens, and underscores, and\nnormalizes the result to lowercase.\n\nFor example, PrimaryUS becomes primaryus. Two configured values that\nnormalize to the same ID make startup fail. Do not encode a rotating token,\nreplica name, or mutable deployment timestamp in the ID.\n\nEvery endpoint in one standalone host belongs to the host's exact\nAIPCONNECTORHOSTTENANTID. An omitted descriptor tenantid inherits that\nvalue. An explicit different value fails startup, and every invocation fails\nclosed unless the trusted runtime tenant matches the endpoint tenant.\n\nUse separate connector instances for different tenants. displayname is\nretained in endpoint configuration at this revision, but it does not affect\nrouting, capability names, or the discovered manifest.\n2. Provision one token file per endpoint\n\nCreate the token through the owner-approved Hermes process and configure the\nsame value as APISERVERKEY on that Hermes API server. Store only the\nconnector-side copy in a dedicated file, for example:\n\n/run/secrets/hermes-primary-api-key\n\nThe connector accepts a non-empty UTF-8 value of at most 16 KiB after trimming\nleading and trailing ASCII whitespace. On Unix, the path must be a regular\nnon-symlink file with no group or world permission bits. A typical mounted-file\nmode is 0600.\n\nKeep these invariants:\n• one endpoint token file identifies one Hermes authentication boundary;\n• the file is mounted read-only into only the replicas that need it;\n• the token never appears in descriptor JSON, action input, admission data,\n  logs, shell history, or a source repository;\n• the file path may be recorded, but its bytes may not be printed as evidence;\n• model-provider, MCP, and webhook credentials remain outside this file.\n\nThe connector excludes token bytes from serialized endpoint configuration and\nredacts its endpoint collection in debug output. Deployment logging and secret\nmount policy must preserve that boundary too.\n3. Write the endpoint descriptor file\n\nCreate a bounded JSON array in an owner-controlled configuration file:\n\n[\n  {\n    \"id\": \"primary\",\n    \"baseurl\": \"https://hermes-primary.example.internal:8642\",\n    \"apikeyfile\": \"/run/secrets/hermes-primary-api-key\",\n    \"displayname\": \"Primary Hermes\",\n    \"tenantid\": \"tenant-acme\"\n  }\n]\n\nPoint AIPHERMESENDPOINTSFILE at this file. Each object has two required\nfields and three optional fields:\n\n| Field | Required | Meaning |\n\n| id | Yes | Stable endpoint segment in every generated capability ID |\n| baseurl | Yes | Owner-selected Hermes API-server origin |\n| apikeyfile | No | File containing the endpoint Bearer token |\n| displayname | No | Human-readable label; never a routing key |\n| tenantid | No | Explicit tenant assertion; otherwise inherits the host tenant |\n\nUnknown fields are rejected. The descriptor file must be a regular\nnon-symlink JSON file of 1 byte through 4 MiB. On Unix it may be group- or\nworld-readable, but it must not be group- or world-writable. It is non-secret\nonly because it contains file references rather than token bytes.\n\nThe parser accepts 1 through 1000 descriptors. That is not the deployable\nlimit. Each endpoint creates 35 capabilities, while the current standalone\nhost accepts at most 512. The effective manifest limit is therefore 14\nendpoints: 14 produce 490 capabilities, while 15 produce 525 and fail host\npreparation. This is a source limit, not a scale qualification.\n4. Validate endpoint identities and destinations\n\nReview the descriptor set before admission:\n1. Normalize every endpoint ID and reject collisions.\n2. Confirm that every explicit tenant equals the host tenant exactly.\n3. Confirm that every URL parses with the http or https scheme.\n4. Resolve each URL through owner-controlled service discovery.\n5. Confirm that every token file belongs to the intended endpoint.\n6. Count 35 × endpoints and keep the result at or below 512.\n\nThe connector accepts both HTTP and HTTPS but does not prove destination\nownership. Use HTTPS outside a controlled loopback or private test network.\nThe default client follows no redirects, so a Hermes response cannot forward\nthe Bearer token to another origin. It uses a 10-second connection timeout and\na 900-second client timeout; individual operations can impose narrower bounds.\n\nRecord the resolved service identity privately. Do not add a caller-controlled\nproxy, URL suffix, or method to action input.\n5. Bind host trust and credential revision\n\nConfigure the standalone host's common identity and trust inputs independently\nfrom the endpoint file. At minimum, the admitted record and running host must\nagree on:\n• connector type, immutable version, instance, and replica IDs;\n• tenant and optional external-account identity;\n• public endpoint, host signing identity, and artifact digest;\n• central gateway principal, DID, and trust domain;\n• opaque credential ID, issuer, verified scopes, and revision reference;\n• credential-revision policy;\n• durable database and control-plane membership.\n\nThe host validates the route-pinned credential revision immediately before\ndispatching provider work. A revision-policy change can therefore stop an old\nroute without changing the Hermes token. Conversely, replacing a Hermes token\ndoes not authorize a different route revision.\n\nUse the shared connector-host configuration reference for exact fields and\nbounds. Keep this page's endpoint descriptor focused on Hermes only.\n6. Start through an admitted deployment\n\nGenerate the manifest from the exact endpoint set, artifact, and host\nconfiguration that will run. Admission must bind that immutable manifest to\nthe intended tenant-owned connector version before the replica becomes\ndiscoverable.\n\nStart the host with the descriptor and secret files already mounted. Startup\nmust fail if:\n• the array is empty, oversized, or invalid JSON;\n• an object has an unknown field;\n• an endpoint ID is invalid or duplicated after normalization;\n• a URL is invalid or uses another scheme;\n• a token file is missing, unsafe, empty, invalid UTF-8, or oversized;\n• an explicit endpoint tenant differs from the host tenant;\n• 35 capabilities per endpoint exceed the host manifest ceiling;\n• the common trust, storage, admission, or credential-revision checks fail.\n\nDo not bypass one of these failures by launching the product connector inside\naipd or by admitting a manifest from a different descriptor set.\n7. Verify selection and authenticated access\n\nUse an already configured signed-native client context. Set the exact tenant\ngateway URL and normalized endpoint ID:\n\nexport AIPURL=https://aip.example\nexport HERMESENDPOINTID=primary\n\nFirst require the endpoint-qualified protected capability in the tenant\ncatalog:\n\naipctl capability list \"$AIPURL\" \\\n  --signed-native \\\n  --capability-id \"cap:hermesagent:${HERMESENDPOINTID}:models\"\n\nExpected result: the bounded catalog page contains exactly the requested\ncapability for the admitted Hermes version. A catalog result proves routing\nmetadata, not token validity.\n\nBasic health is deliberately unauthenticated and cannot prove the endpoint\ntoken. Call the protected models read instead:\n\naipctl action call \\\n  \"$AIPURL\" \\\n  \"cap:hermesagent:${HERMESENDPOINTID}:models\" \\\n  --action-id acthermesendpointauth001 \\\n  --input '{}'\n\nExpected result: the action reaches a terminal completed state and returns the\nHermes model catalog. Correlate the action ID, connector version, instance,\nreplica, endpoint ID, tenant, and provider audit record without retaining the\nBearer token.\n\nA completed protected read demonstrates that the selected endpoint possessed\na usable token at that time. It does not prove that every model-provider\ncredential, mutation, stream, operator policy, or delegation path works.\n8. Rotate an endpoint token\n\nThe standalone binary reads each API-key file once during startup. Replacing\nthe mounted file alone does not update a running process.\n\nFor a routine rotation:\n1. Create a new Hermes token and a new immutable connector-side secret file.\n2. Keep the old token valid while replacement replicas start.\n3. Start new replicas with the same admitted endpoint manifest and new token\n   bytes, using new replica identities.\n4. Require host readiness and repeat the protected models read through a\n   controlled route.\n5. Stop new assignments to old replicas and let their pinned actions settle.\n6. Drain and take the old replicas offline.\n7. Revoke the old Hermes token.\n8. Retain secret-free action, host, registry, and provider evidence.\n\nThe endpoint manifest need not change when only secret bytes change. The\nprocess still must be replaced or restarted so it loads the new bytes. If the\ncredential revision also changes, use the full blue/green instance procedure\nand preserve old pinned assignments under their original revision.\n\nFor a suspected compromise, first stop new routing and revoke the affected\nrevision or token according to the incident boundary. Do not prioritize a\ngraceful overlap over containment.\n\nResolve authentication and endpoint failures\n\n| Symptom | Likely boundary | Safe decision |\n\n| Host rejects descriptor JSON | Shape, size, unknown field, or file permissions | Correct the owner-controlled file; do not relax parsing |\n| Duplicate endpoint error | IDs collide after trimming and lowercase normalization | Assign distinct stable IDs and create a new manifest |\n| Tenant mismatch at startup | Descriptor tenant differs from host tenant | Move the endpoint to the correct tenant instance |\n| connector.hermesagent.tenantmismatch | Trusted runtime tenant is absent or different | Repair admission and routing; never override tenant in input |\n| connector.hermesagent.missingcredential | Protected operation has no usable endpoint key | Mount the correct owner-only file and replace the process |\n| Provider returns 401 or 403 | Token is invalid, revoked, or insufficient | Check the exact endpoint and provider audit; rotate or scope correctly |\n| Basic health passes but models fails | /health does not require endpoint auth | Diagnose the protected credential path; do not accept health as proof |\n| Catalog lacks the endpoint capability | Admitted manifest or binding differs | Reconcile version, instance, binding, and endpoint set |\n| Old token remains in use after file replacement | Running process retained startup bytes | Replace or restart the affected replica safely |\n| Request tries another origin after redirect | Provider returned redirect | Correct the configured base URL; redirects remain disabled |\n\nDo not retry a state-changing action merely because an authentication or\ntransport error appears retryable. Preserve the original action ID and use the\noperation-specific reconciliation guidance.\n\nRelated documentation\n• Hermes Agent connector (../README.md)\n• Hermes Agent quickstart (quickstart.md)\n• Rotate connector credentials (../../../guides/connector-credentials-and-rotation.md)\n• Connector registry and routing (../../../architecture/connector-registry-and-routing.md)\n• Security model (../../../architecture/security-model.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "217dbdde19913b470cf1597c4fdcb29137d80cf4cb9a5b5c6540710d32229164"
  }
}