{
  "schemaVersion": "1.0",
  "title": "Dify authentication and credential scopes",
  "description": "The Dify connector crosses several identity boundaries in one Action. Keep each identity in its source-owned layer so a caller cannot select a provider credential, another workspace, or another end user's conversation context.",
  "canonical": "https://getaip.org/docs/connectors/dify/getting-started/authentication-and-credential-scopes",
  "route": "/docs/connectors/dify/getting-started/authentication-and-credential-scopes",
  "source": "docs/connectors/dify/getting-started/authentication-and-credential-scopes.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/dify/getting-started/authentication-and-credential-scopes.md",
    "txt": "/docs/download/connectors/dify/getting-started/authentication-and-credential-scopes.txt",
    "json": "/docs/download/connectors/dify/getting-started/authentication-and-credential-scopes.json",
    "pdf": "/docs/download/connectors/dify/getting-started/authentication-and-credential-scopes.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Dify authentication and credential scopes\ndescription: >-\n  Separate Dify application keys, Knowledge keys, AIP tenant authority, and\n  end-user identity\nkind: explanation\naudience: security-engineer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: dify\n---\n\n# Dify authentication and credential scopes\n\nThe Dify connector crosses several identity boundaries in one Action. Keep\neach identity in its source-owned layer so a caller cannot select a provider\ncredential, another workspace, or another end user's conversation context.\n\nThis page explains the boundaries and rotation decisions. It does not grant a\nprovider scope or replace the deployment's tenant and secret policy.\n\n## Separate the four identity layers\n\n| Layer | Trusted source | Purpose | Must not select it |\n|---|---|---|---|\n| AIP caller | Verified signed envelope and membership | Authorizes the tenant Action | Untrusted request metadata |\n| Connector host | Admitted instance, replica, artifact, manifest, and route | Fixes the executable and tenant boundary | Action input |\n| Dify credential | Owner-controlled host configuration and key file | Authenticates one app or Knowledge domain | Action body, query, or file data |\n| Dify end user | Validated Action field mapped by the chosen capability | Isolates user-bound provider data | Connector-wide fallback or bearer token |\n\nThe signed AIP route selects an admitted host. The capability ID then selects\none descriptor already loaded by that host. Only after both checks does the\nconnector choose a Bearer key from its protected map.\n\n## Scope application keys per app\n\nA Dify Service API key is application-scoped. The standalone host supports two\nconfiguration forms:\n\n| Form | Intended use | Constraint |\n|---|---|---|\n| Per-app `api_key_file` | Normal production isolation | Every app names the file for its own key |\n| Global `AIP_DIFY_API_KEY_FILE` | Intentional shared-key compatibility | Every configured app omits `api_key_file` and truly shares that key |\n\nThe host rejects an app that combines a per-app file with the global key. It\nalso rejects an app with neither source. A global key without at least one app\nis invalid.\n\nPrefer one file and one provider key per app. Shared material enlarges the\nblast radius of rotation, provider compromise, and descriptor misbinding.\nNever copy an app key into an Action, descriptor description, log, image,\nmanifest, or public configuration file.\n\n## Scope Knowledge keys per workspace boundary\n\nEvery Knowledge descriptor requires its own `api_key_file`. The connector uses\nthat key only for capabilities under:\n\n```text\ncap:dify:knowledge:<credential_id>:<operation>\n```\n\nThe local `credential_id` is a public routing label, not a provider secret. It\nmust map to the intended Dify workspace and remain stable for the lifetime of\nan admitted connector version.\n\nAn application key and a Knowledge key are not interchangeable. A successful\napp health probe does not prove Knowledge access, and a dataset read does not\nprove app access.\n\n## Keep provider selection outside the Action\n\nThe host accepts one Dify base origin and static descriptor sets at startup.\nAction input cannot override:\n\n- provider scheme, host, port, or path;\n- app ID or Knowledge credential ID outside the capability;\n- key file or Bearer value;\n- connector instance, tenant, artifact, manifest, or credential revision.\n\nThe base URL must be an origin without credentials, path prefix, query, or\nfragment. HTTPS is required except for explicit loopback. Redirects are\ndisabled, so a provider cannot move a signed request and its Bearer key to a\ndifferent origin through HTTP redirection.\n\n## Preserve Dify end-user identity\n\nApp invocation aliases require `user`. Catalogue operations require it only\nwhen their frozen route declares a query, JSON, or multipart user location.\nThe value must contain 1 to 256 bytes without control characters.\n\nUse a stable, opaque, non-secret value derived under tenant policy. It should\nnot reveal an email address, phone number, credential, or internal database\nkey.\n\nThe connector rejects a `user` that conflicts with another input partition.\nIt cannot determine whether two valid values represent different people.\nReusing one value across tenants or users can merge Dify conversations,\nmessages, feedback, files, or cancellation authority.\n\nKnowledge operations do not inject an end-user value. Their provider boundary\nis the selected workspace key, while AIP tenant policy still governs who may\ninvoke the capability.\n\n## Understand credential metadata\n\nDiscovery exposes only the credential class and public descriptor ID:\n\n| Surface | Auth metadata |\n|---|---|\n| App invocation alias | `dify_app_api_key` |\n| App catalogue operation | `dify_app_api_key` plus app descriptor ID |\n| Knowledge operation | `dify_knowledge_api_key` plus Knowledge descriptor ID |\n\nThe connector's debug formatter replaces both key maps with `[REDACTED]`.\nThat reduces accidental diagnostics exposure, but it does not sanitize every\nexternal logger, crash dump, process inspection surface, or provider response.\n\nThe connector publishes `credentials: false` in implementation support. It\ndoes not accept AIP credential handles or dynamically resolve caller-selected\nsecrets at this revision.\n\n## Provision a credential safely\n\nBefore admitting a host:\n\n1. create a least-authority provider key for the exact app or Knowledge\n   workspace;\n2. write it to a dedicated owner-only file of at most 16 KiB;\n3. keep descriptor JSON public only if it contains no secret material;\n4. bind each descriptor ID to the reviewed key file and provider account;\n5. bind the host to one AIP tenant and immutable connector identity;\n6. admit the exact artifact and manifest before starting Action traffic;\n7. verify `/ready` and one safe read through the normal gateway route;\n8. record the credential revision without recording the key.\n\nDo not test a key by printing it or placing it on a command line. Use the\nconfigured host and a non-mutating capability whose provider scope is known.\n\n## Rotate without widening authority\n\nKeys are loaded when the host process is constructed. Rotation therefore uses\na controlled replacement:\n\n1. pause new unsafe Actions for the affected descriptor;\n2. identify in-flight Actions and remote Dify tasks;\n3. create a new provider key with the same reviewed scope;\n4. write a new owner-only file and update the intended credential revision;\n5. admit the replacement version, then start its host with immutable metadata;\n6. require readiness and one gateway-routed read for the affected credential;\n7. drain the old replica while preserving task correlation and Action state;\n8. revoke the old provider key only after traffic and recovery ownership move;\n9. retain redacted evidence and remove the old file under secret policy.\n\nDo not rotate an app key, Knowledge key, tenant binding, descriptor ID, provider\norigin, and connector version in one opaque change. Separate evidence makes a\nfailed boundary and rollback target identifiable.\n\n## Respond to credential incidents\n\nTreat unexpected account data, cross-user conversations, provider `401` or\n`403` after a known-good state, descriptor drift, or key exposure as an\nauthentication or isolation incident.\n\nContain the affected descriptor without disabling unrelated credentials. Keep\nAction IDs, capability IDs, tenant, instance, credential revision, remote\nstatus, and redacted provider account evidence. Do not retain Bearer values,\nraw personal content, or secret-file bytes in the incident bundle.\n\nAfter correction, require AIP signature and route verification, host readiness,\nthe exact credential's safe health path, and provider-state reconciliation for\nevery uncertain mutation. A green process `/health` response is insufficient.\n\n## Related documentation\n\n- [Dify connector overview](../README.md)\n- [Run the Dify quickstart](quickstart.md)\n- [Identity and trust](../../../concepts/identity-and-trust.md)\n- [Connector credentials and rotation](../../../guides/connector-credentials-and-rotation.md)\n- [Errors and retry decisions](../../../reference/errors.md)\n",
    "text": "Dify authentication and credential scopes\n\nThe Dify connector crosses several identity boundaries in one Action. Keep\neach identity in its source-owned layer so a caller cannot select a provider\ncredential, another workspace, or another end user's conversation context.\n\nThis page explains the boundaries and rotation decisions. It does not grant a\nprovider scope or replace the deployment's tenant and secret policy.\n\nSeparate the four identity layers\n\n| Layer | Trusted source | Purpose | Must not select it |\n\n| AIP caller | Verified signed envelope and membership | Authorizes the tenant Action | Untrusted request metadata |\n| Connector host | Admitted instance, replica, artifact, manifest, and route | Fixes the executable and tenant boundary | Action input |\n| Dify credential | Owner-controlled host configuration and key file | Authenticates one app or Knowledge domain | Action body, query, or file data |\n| Dify end user | Validated Action field mapped by the chosen capability | Isolates user-bound provider data | Connector-wide fallback or bearer token |\n\nThe signed AIP route selects an admitted host. The capability ID then selects\none descriptor already loaded by that host. Only after both checks does the\nconnector choose a Bearer key from its protected map.\n\nScope application keys per app\n\nA Dify Service API key is application-scoped. The standalone host supports two\nconfiguration forms:\n\n| Form | Intended use | Constraint |\n\n| Per-app apikeyfile | Normal production isolation | Every app names the file for its own key |\n| Global AIPDIFYAPIKEYFILE | Intentional shared-key compatibility | Every configured app omits apikeyfile and truly shares that key |\n\nThe host rejects an app that combines a per-app file with the global key. It\nalso rejects an app with neither source. A global key without at least one app\nis invalid.\n\nPrefer one file and one provider key per app. Shared material enlarges the\nblast radius of rotation, provider compromise, and descriptor misbinding.\nNever copy an app key into an Action, descriptor description, log, image,\nmanifest, or public configuration file.\n\nScope Knowledge keys per workspace boundary\n\nEvery Knowledge descriptor requires its own apikeyfile. The connector uses\nthat key only for capabilities under:\n\ncap:dify:knowledge::\n\nThe local credentialid is a public routing label, not a provider secret. It\nmust map to the intended Dify workspace and remain stable for the lifetime of\nan admitted connector version.\n\nAn application key and a Knowledge key are not interchangeable. A successful\napp health probe does not prove Knowledge access, and a dataset read does not\nprove app access.\n\nKeep provider selection outside the Action\n\nThe host accepts one Dify base origin and static descriptor sets at startup.\nAction input cannot override:\n• provider scheme, host, port, or path;\n• app ID or Knowledge credential ID outside the capability;\n• key file or Bearer value;\n• connector instance, tenant, artifact, manifest, or credential revision.\n\nThe base URL must be an origin without credentials, path prefix, query, or\nfragment. HTTPS is required except for explicit loopback. Redirects are\ndisabled, so a provider cannot move a signed request and its Bearer key to a\ndifferent origin through HTTP redirection.\n\nPreserve Dify end-user identity\n\nApp invocation aliases require user. Catalogue operations require it only\nwhen their frozen route declares a query, JSON, or multipart user location.\nThe value must contain 1 to 256 bytes without control characters.\n\nUse a stable, opaque, non-secret value derived under tenant policy. It should\nnot reveal an email address, phone number, credential, or internal database\nkey.\n\nThe connector rejects a user that conflicts with another input partition.\nIt cannot determine whether two valid values represent different people.\nReusing one value across tenants or users can merge Dify conversations,\nmessages, feedback, files, or cancellation authority.\n\nKnowledge operations do not inject an end-user value. Their provider boundary\nis the selected workspace key, while AIP tenant policy still governs who may\ninvoke the capability.\n\nUnderstand credential metadata\n\nDiscovery exposes only the credential class and public descriptor ID:\n\n| Surface | Auth metadata |\n\n| App invocation alias | difyappapikey |\n| App catalogue operation | difyappapikey plus app descriptor ID |\n| Knowledge operation | difyknowledgeapikey plus Knowledge descriptor ID |\n\nThe connector's debug formatter replaces both key maps with [REDACTED].\nThat reduces accidental diagnostics exposure, but it does not sanitize every\nexternal logger, crash dump, process inspection surface, or provider response.\n\nThe connector publishes credentials: false in implementation support. It\ndoes not accept AIP credential handles or dynamically resolve caller-selected\nsecrets at this revision.\n\nProvision a credential safely\n\nBefore admitting a host:\n1. create a least-authority provider key for the exact app or Knowledge\n   workspace;\n2. write it to a dedicated owner-only file of at most 16 KiB;\n3. keep descriptor JSON public only if it contains no secret material;\n4. bind each descriptor ID to the reviewed key file and provider account;\n5. bind the host to one AIP tenant and immutable connector identity;\n6. admit the exact artifact and manifest before starting Action traffic;\n7. verify /ready and one safe read through the normal gateway route;\n8. record the credential revision without recording the key.\n\nDo not test a key by printing it or placing it on a command line. Use the\nconfigured host and a non-mutating capability whose provider scope is known.\n\nRotate without widening authority\n\nKeys are loaded when the host process is constructed. Rotation therefore uses\na controlled replacement:\n1. pause new unsafe Actions for the affected descriptor;\n2. identify in-flight Actions and remote Dify tasks;\n3. create a new provider key with the same reviewed scope;\n4. write a new owner-only file and update the intended credential revision;\n5. admit the replacement version, then start its host with immutable metadata;\n6. require readiness and one gateway-routed read for the affected credential;\n7. drain the old replica while preserving task correlation and Action state;\n8. revoke the old provider key only after traffic and recovery ownership move;\n9. retain redacted evidence and remove the old file under secret policy.\n\nDo not rotate an app key, Knowledge key, tenant binding, descriptor ID, provider\norigin, and connector version in one opaque change. Separate evidence makes a\nfailed boundary and rollback target identifiable.\n\nRespond to credential incidents\n\nTreat unexpected account data, cross-user conversations, provider 401 or\n403 after a known-good state, descriptor drift, or key exposure as an\nauthentication or isolation incident.\n\nContain the affected descriptor without disabling unrelated credentials. Keep\nAction IDs, capability IDs, tenant, instance, credential revision, remote\nstatus, and redacted provider account evidence. Do not retain Bearer values,\nraw personal content, or secret-file bytes in the incident bundle.\n\nAfter correction, require AIP signature and route verification, host readiness,\nthe exact credential's safe health path, and provider-state reconciliation for\nevery uncertain mutation. A green process /health response is insufficient.\n\nRelated documentation\n• Dify connector overview (../README.md)\n• Run the Dify quickstart (quickstart.md)\n• Identity and trust (../../../concepts/identity-and-trust.md)\n• Connector credentials and rotation (../../../guides/connector-credentials-and-rotation.md)\n• Errors and retry decisions (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "abdd95890323b75fc314533159bb2670a968af290a7ffe13b5bac93c97aa6864"
  }
}