{
  "schemaVersion": "1.0",
  "title": "CrewAI authentication and admitted crews",
  "description": "The CrewAI integration has three distinct trust boundaries. Keeping them separate prevents an AIP caller from selecting Python code, changing the sidecar identity, or supplying deployment credentials through an Action.",
  "canonical": "https://getaip.org/docs/connectors/crewai/getting-started/authentication-and-admitted-crews",
  "route": "/docs/connectors/crewai/getting-started/authentication-and-admitted-crews",
  "source": "docs/connectors/crewai/getting-started/authentication-and-admitted-crews.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/crewai/getting-started/authentication-and-admitted-crews.md",
    "txt": "/docs/download/connectors/crewai/getting-started/authentication-and-admitted-crews.txt",
    "json": "/docs/download/connectors/crewai/getting-started/authentication-and-admitted-crews.json",
    "pdf": "/docs/download/connectors/crewai/getting-started/authentication-and-admitted-crews.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: CrewAI authentication and admitted crews\ndescription: >-\n  Separate AIP caller trust, host-to-sidecar authentication, admitted crew\n  policy, and deployment-owned CrewAI credentials\nkind: explanation\naudience: security-engineer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: crewai\n---\n\n# CrewAI authentication and admitted crews\n\nThe CrewAI integration has three distinct trust boundaries. Keeping them\nseparate prevents an AIP caller from selecting Python code, changing the\nsidecar identity, or supplying deployment credentials through an Action.\n\nThis page owns that boundary model. It does not enumerate every configuration\nvalue or replace tenant admission, operation policy, and production rollout\ncontrols.\n\n## Separate the three trust boundaries\n\n| Boundary | Trusted input | Enforced by | Protected decision |\n|---|---|---|---|\n| Caller to AIP | Verified envelope, principal, membership, tenant, and route | AIP edge, runtime, and connector host | Which admitted capability may receive the Action |\n| Rust host to Python sidecar | Fixed sidecar base URL and bearer token | `aip-host-crewai` and `aip-crewai-sidecar` | Which host may call the private execution API |\n| Sidecar to CrewAI dependencies | Deployment-owned registry, crew code, models, tools, and provider secrets | Sidecar deployment and crew implementation | What trusted Python code and external authority execute |\n\nOne credential cannot substitute for another. A caller token does not\nauthenticate the Rust host to the sidecar. The sidecar bearer does not grant\nmodel, tool, memory, or knowledge access.\n\n## Keep AIP identity outside Action input\n\nThe signed AIP route selects an admitted standalone host. Verified execution\ncontext carries the tenant and host binding before the connector interprets\nthe capability ID.\n\nAn Action may select only an operation already published for its capability.\nIt cannot provide:\n\n- a tenant, connector instance, replica, or registry route;\n- a Python module, registry attribute, or crew ID outside the capability;\n- a sidecar origin or bearer token;\n- a host signing key, credential revision, or admission identity;\n- a model, tool, or provider credential through connector metadata.\n\nThe connector uses the verified tenant when it builds execution and\nidempotency context. Untrusted body fields do not replace that value.\n\n## Protect the host-to-sidecar channel\n\nThe Rust host requires a fixed `AIP_CREWAI_SIDECAR_URL`. The reviewed source\nrejects credentials, a query, or a fragment.\n\nIt does not reject a path prefix. Internal joins use absolute paths such as\n`/health` and `/jobs`, which discard that prefix. Configure an origin-only URL\nso the deployed route matches the value an operator reviews.\n\nHTTPS is required except for an explicit loopback origin. Redirects are\ndisabled, so the host does not forward its bearer credential to a redirected\ndestination.\n\nProduction startup also requires `AIP_CREWAI_SIDECAR_TOKEN_FILE`. The host\nloads the owner-held value and adds it as an HTTP Bearer credential to health,\njob, event, and cancellation requests.\n\nThe host accepts a regular owner-only file of 1 byte through 16 KiB, trims\nsurrounding ASCII whitespace, and requires non-empty UTF-8. The connector then\nrejects an empty value or any control character.\n\nThe reviewed connector does not reject an interior plain space or apply a\nsecond explicit length check after file loading. Its debug representation\nreports only whether a token is configured.\n\nPlace the host and sidecar on a private network even when HTTPS and bearer\nauthentication are present. The sidecar API can start deployment-authored\nPython code and must not be exposed as a tenant-facing endpoint.\n\n## Provision the sidecar token file\n\nThe Python sidecar accepts one of two mutually exclusive token sources:\n\n```text\nAIP_CREWAI_BEARER_TOKEN_FILE=/run/secrets/crewai-sidecar-token\nAIP_CREWAI_BEARER_TOKEN=<inline-development-value>\n```\n\nUse the file form for a controlled deployment. The sidecar requires the path\nto be a regular non-symlink file with no group or world permission bits. It\naccepts between 1 byte and 16 KiB.\n\nThe sidecar opens the file without following a symlink when the platform\nsupports that flag. It compares the opened device and inode with the inspected\nfile, decodes UTF-8, and strips surrounding whitespace.\n\nEvery protected route compares the complete `Authorization` value in constant\ntime. Missing or invalid material returns `401` with a Bearer challenge.\n\nDo not place the token in:\n\n- a crew descriptor, Action input, manifest, capability, or registry entry;\n- a command-line argument, image layer, public configuration, or evidence file;\n- model, tool, memory, or knowledge configuration;\n- an AIP credential handle or external-account label.\n\nThe source permits unauthenticated operation only when the sidecar bind host is\nloopback and `AIP_CREWAI_ALLOW_UNAUTHENTICATED=true`. Both conditions are\nrequired. This exception is a local-development boundary, not a production\ndeployment option.\n\n## Admit crews through host descriptors\n\n`AIP_CREWAI_CREWS_FILE` is a bounded JSON array loaded before the host joins\nthe fleet. The file must contain between one and 1,000 descriptors and may not\nexceed 4 MiB.\n\nEach descriptor has this public shape:\n\n```json\n{\n  \"id\": \"support-primary\",\n  \"name\": \"Support primary\",\n  \"description\": \"Routes reviewed support cases\",\n  \"allowed_operations\": [\"run\", \"status\", \"events\", \"cancel\"]\n}\n```\n\nThe host applies these checks:\n\n| Field | Constraint |\n|---|---|\n| `id` | Non-empty after trimming, no control characters, unique, and valid inside each derived AIP capability ID |\n| `name` | Non-empty after trimming |\n| `description` | Optional; no field-specific bound or character check at this revision |\n| `allowed_operations` | Non-empty set of known CrewAI operations with valid derived capability IDs |\n\nThe 4 MiB file ceiling bounds the combined descriptor payload. It is not a\nsubstitute for field-specific name and description policy. Apply tighter\ndeployment validation before generating public manifest text.\n\nA descriptor that omits `allowed_operations` receives the compatibility\npolicy `run`, `status`, `events`, and `cancel`. New deployments should state\nthe intended set explicitly so a source-default change cannot widen policy\nsilently.\n\nThe descriptor admits a public crew identity and operation surface. It does\nnot load Python code or prove that a provider credential has the intended\nscope.\n\n## Bind descriptors to a private registry\n\nThe sidecar loads `AIP_CREWAI_REGISTRY` using `module:attribute` syntax. The\nreferenced attribute must be a non-empty mapping or a zero-argument callable\nthat returns one.\n\nMapping keys are non-empty crew IDs. Each value must be a zero-argument factory\nor a cloneable Crew instance.\n\nThe sidecar calls the factory or creates a deep clone for each job. This\nprevents mutable CrewAI objects from being reused across requests by the\nregistry layer. It does not sandbox the resulting Python code.\n\nThe registry may contain crews that the host does not advertise. A caller\nstill cannot reach them because the Rust descriptor owns capability\npublication and routing.\n\nEvery host-admitted crew must exist in the registry. Authenticated sidecar\nhealth publishes its available crew IDs, and host readiness fails when an\nadmitted ID is absent.\n\n## Align both operation allowlists\n\nThe Rust descriptor may admit any subset of the ten frozen operations. The\nsidecar environment admits only operations that can start jobs:\n\n```text\nrun,batch_run,replay,train,test,knowledge_query,memory_reset\n```\n\n`status`, `events`, and `cancel` are control operations. The sidecar serves and\nreports them automatically instead of accepting them in\n`AIP_CREWAI_ALLOWED_OPERATIONS`.\n\nThe sidecar default admits only `run`. Host readiness compares each descriptor\nallowlist with the authenticated health response. A host that advertises an\noperation missing from sidecar health remains unready.\n\nUse the intersection intentionally:\n\n1. review the crew code and its model, tool, memory, and knowledge effects;\n2. enable only the sidecar job operations required by that deployment;\n3. give each host descriptor the same or a narrower operation policy;\n4. admit the resulting capabilities for the intended tenant;\n5. verify authenticated health before enabling traffic.\n\nNever repair a readiness failure by enabling every operation without reviewing\nthe added side effects. Training and memory reset have materially different\nrisk from status and event reads.\n\n## Keep CrewAI credentials deployment-owned\n\nCrew factories may obtain model, evaluator, tool, storage, tracing, memory, or\nknowledge credentials through deployment-controlled code and secret mounts.\nThe connector does not resolve those credentials from an Action.\n\nIts implementation support declares dynamic AIP credential handling as\nunsupported. Provider credentials therefore remain outside the connector's\ncapability schema and discovery output.\n\nApply least authority to each dependency. A crew that only classifies local\nrecords should not inherit a credential that can mutate an unrelated provider.\nTreat tools as executable code with their own network and data boundaries.\n\nTelemetry is disabled in the controlled fleet profile. Enabling CrewAI or\nOpenTelemetry tracing requires a separate review of content, credential, and\ndestination exposure.\n\n## Isolate tenants and active processes\n\nUse one connector instance for one reviewed tenant, descriptor set, registry,\nsidecar token, and durable sidecar state boundary. Deployment metadata may\nalso record an external account, but the reviewed CrewAI host does not compare\nthat label with a descriptor ID automatically.\n\nOnly one active sidecar process may own a state journal. Horizontal scaling\nuses independent connector instances with independent state volumes, tokens,\nreplica identities, and routes.\n\nDo not mount one journal into active replicas. The local file lock is a\nsingle-writer process fence, not a distributed coordinator.\n\n## Rotate without splitting the boundary\n\nThe host and sidecar load their authentication and admission inputs at startup.\nTreat rotation as a coordinated replacement rather than an undocumented live\nreload.\n\n1. freeze new unsafe assignment to the affected instance;\n2. inventory running jobs and preserve their Action IDs and journal owner;\n3. create a new token file and, when needed, a reviewed descriptor or registry\n   revision;\n4. start a replacement sidecar against a new or deliberately transferred\n   state boundary;\n5. start its matching Rust host with the same new token and fixed origin;\n6. require authenticated health, descriptor agreement, and expected discovery;\n7. route new Actions only after those checks pass;\n8. drain the old instance before revoking its token or removing its state;\n9. retain redacted identity and transition evidence.\n\nNever let an old host authenticate to a new sidecar unintentionally. Never\ndelete a journal while a job outcome may still be uncertain.\n\n## Diagnose boundary failures\n\n| Symptom | Decision |\n|---|---|\n| Host rejects the token | Check file type, permissions, UTF-8, length, and prohibited characters without printing it |\n| Sidecar returns `401` | Compare the mounted token sources and restart ownership; do not put the value in a diagnostic command |\n| Sidecar refuses startup without a token | Configure the protected file, or bind loopback and enable the explicit development exception |\n| Descriptor is rejected | Check file count and size, non-empty IDs and names, ID controls, uniqueness, capability syntax, and operation sets |\n| Registry fails to load | Verify `module:attribute`, importability, mapping shape, IDs, and factory or clone behavior |\n| Host is healthy but not ready | Compare admitted crew IDs and operations with authenticated sidecar health |\n| A crew is present only in the registry | Add a reviewed host descriptor and admission policy before exposing it |\n| Provider returns an authentication error | Investigate the crew-owned model, tool, or provider credential, not the sidecar token |\n| Data appears across tenant boundaries | Disable routing and reconcile tenant, instance, descriptor, registry, state volume, and provider authority |\n\nPreserve Action ID, tenant, instance, replica, descriptor revision, sidecar\nartifact, registry identity, credential revision, and redacted error category.\nDo not retain token bytes or raw model and tool content by default.\n\n## Related documentation\n\n- [CrewAI connector overview](../README.md)\n- [Run the CrewAI 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": "CrewAI authentication and admitted crews\n\nThe CrewAI integration has three distinct trust boundaries. Keeping them\nseparate prevents an AIP caller from selecting Python code, changing the\nsidecar identity, or supplying deployment credentials through an Action.\n\nThis page owns that boundary model. It does not enumerate every configuration\nvalue or replace tenant admission, operation policy, and production rollout\ncontrols.\n\nSeparate the three trust boundaries\n\n| Boundary | Trusted input | Enforced by | Protected decision |\n\n| Caller to AIP | Verified envelope, principal, membership, tenant, and route | AIP edge, runtime, and connector host | Which admitted capability may receive the Action |\n| Rust host to Python sidecar | Fixed sidecar base URL and bearer token | aip-host-crewai and aip-crewai-sidecar | Which host may call the private execution API |\n| Sidecar to CrewAI dependencies | Deployment-owned registry, crew code, models, tools, and provider secrets | Sidecar deployment and crew implementation | What trusted Python code and external authority execute |\n\nOne credential cannot substitute for another. A caller token does not\nauthenticate the Rust host to the sidecar. The sidecar bearer does not grant\nmodel, tool, memory, or knowledge access.\n\nKeep AIP identity outside Action input\n\nThe signed AIP route selects an admitted standalone host. Verified execution\ncontext carries the tenant and host binding before the connector interprets\nthe capability ID.\n\nAn Action may select only an operation already published for its capability.\nIt cannot provide:\n• a tenant, connector instance, replica, or registry route;\n• a Python module, registry attribute, or crew ID outside the capability;\n• a sidecar origin or bearer token;\n• a host signing key, credential revision, or admission identity;\n• a model, tool, or provider credential through connector metadata.\n\nThe connector uses the verified tenant when it builds execution and\nidempotency context. Untrusted body fields do not replace that value.\n\nProtect the host-to-sidecar channel\n\nThe Rust host requires a fixed AIPCREWAISIDECARURL. The reviewed source\nrejects credentials, a query, or a fragment.\n\nIt does not reject a path prefix. Internal joins use absolute paths such as\n/health and /jobs, which discard that prefix. Configure an origin-only URL\nso the deployed route matches the value an operator reviews.\n\nHTTPS is required except for an explicit loopback origin. Redirects are\ndisabled, so the host does not forward its bearer credential to a redirected\ndestination.\n\nProduction startup also requires AIPCREWAISIDECARTOKENFILE. The host\nloads the owner-held value and adds it as an HTTP Bearer credential to health,\njob, event, and cancellation requests.\n\nThe host accepts a regular owner-only file of 1 byte through 16 KiB, trims\nsurrounding ASCII whitespace, and requires non-empty UTF-8. The connector then\nrejects an empty value or any control character.\n\nThe reviewed connector does not reject an interior plain space or apply a\nsecond explicit length check after file loading. Its debug representation\nreports only whether a token is configured.\n\nPlace the host and sidecar on a private network even when HTTPS and bearer\nauthentication are present. The sidecar API can start deployment-authored\nPython code and must not be exposed as a tenant-facing endpoint.\n\nProvision the sidecar token file\n\nThe Python sidecar accepts one of two mutually exclusive token sources:\n\nAIPCREWAIBEARERTOKENFILE=/run/secrets/crewai-sidecar-token\nAIPCREWAIBEARERTOKEN=\n\nUse the file form for a controlled deployment. The sidecar requires the path\nto be a regular non-symlink file with no group or world permission bits. It\naccepts between 1 byte and 16 KiB.\n\nThe sidecar opens the file without following a symlink when the platform\nsupports that flag. It compares the opened device and inode with the inspected\nfile, decodes UTF-8, and strips surrounding whitespace.\n\nEvery protected route compares the complete Authorization value in constant\ntime. Missing or invalid material returns 401 with a Bearer challenge.\n\nDo not place the token in:\n• a crew descriptor, Action input, manifest, capability, or registry entry;\n• a command-line argument, image layer, public configuration, or evidence file;\n• model, tool, memory, or knowledge configuration;\n• an AIP credential handle or external-account label.\n\nThe source permits unauthenticated operation only when the sidecar bind host is\nloopback and AIPCREWAIALLOWUNAUTHENTICATED=true. Both conditions are\nrequired. This exception is a local-development boundary, not a production\ndeployment option.\n\nAdmit crews through host descriptors\n\nAIPCREWAICREWSFILE is a bounded JSON array loaded before the host joins\nthe fleet. The file must contain between one and 1,000 descriptors and may not\nexceed 4 MiB.\n\nEach descriptor has this public shape:\n\n{\n  \"id\": \"support-primary\",\n  \"name\": \"Support primary\",\n  \"description\": \"Routes reviewed support cases\",\n  \"allowedoperations\": [\"run\", \"status\", \"events\", \"cancel\"]\n}\n\nThe host applies these checks:\n\n| Field | Constraint |\n\n| id | Non-empty after trimming, no control characters, unique, and valid inside each derived AIP capability ID |\n| name | Non-empty after trimming |\n| description | Optional; no field-specific bound or character check at this revision |\n| allowedoperations | Non-empty set of known CrewAI operations with valid derived capability IDs |\n\nThe 4 MiB file ceiling bounds the combined descriptor payload. It is not a\nsubstitute for field-specific name and description policy. Apply tighter\ndeployment validation before generating public manifest text.\n\nA descriptor that omits allowedoperations receives the compatibility\npolicy run, status, events, and cancel. New deployments should state\nthe intended set explicitly so a source-default change cannot widen policy\nsilently.\n\nThe descriptor admits a public crew identity and operation surface. It does\nnot load Python code or prove that a provider credential has the intended\nscope.\n\nBind descriptors to a private registry\n\nThe sidecar loads AIPCREWAIREGISTRY using module:attribute syntax. The\nreferenced attribute must be a non-empty mapping or a zero-argument callable\nthat returns one.\n\nMapping keys are non-empty crew IDs. Each value must be a zero-argument factory\nor a cloneable Crew instance.\n\nThe sidecar calls the factory or creates a deep clone for each job. This\nprevents mutable CrewAI objects from being reused across requests by the\nregistry layer. It does not sandbox the resulting Python code.\n\nThe registry may contain crews that the host does not advertise. A caller\nstill cannot reach them because the Rust descriptor owns capability\npublication and routing.\n\nEvery host-admitted crew must exist in the registry. Authenticated sidecar\nhealth publishes its available crew IDs, and host readiness fails when an\nadmitted ID is absent.\n\nAlign both operation allowlists\n\nThe Rust descriptor may admit any subset of the ten frozen operations. The\nsidecar environment admits only operations that can start jobs:\n\nrun,batchrun,replay,train,test,knowledgequery,memoryreset\n\nstatus, events, and cancel are control operations. The sidecar serves and\nreports them automatically instead of accepting them in\nAIPCREWAIALLOWEDOPERATIONS.\n\nThe sidecar default admits only run. Host readiness compares each descriptor\nallowlist with the authenticated health response. A host that advertises an\noperation missing from sidecar health remains unready.\n\nUse the intersection intentionally:\n1. review the crew code and its model, tool, memory, and knowledge effects;\n2. enable only the sidecar job operations required by that deployment;\n3. give each host descriptor the same or a narrower operation policy;\n4. admit the resulting capabilities for the intended tenant;\n5. verify authenticated health before enabling traffic.\n\nNever repair a readiness failure by enabling every operation without reviewing\nthe added side effects. Training and memory reset have materially different\nrisk from status and event reads.\n\nKeep CrewAI credentials deployment-owned\n\nCrew factories may obtain model, evaluator, tool, storage, tracing, memory, or\nknowledge credentials through deployment-controlled code and secret mounts.\nThe connector does not resolve those credentials from an Action.\n\nIts implementation support declares dynamic AIP credential handling as\nunsupported. Provider credentials therefore remain outside the connector's\ncapability schema and discovery output.\n\nApply least authority to each dependency. A crew that only classifies local\nrecords should not inherit a credential that can mutate an unrelated provider.\nTreat tools as executable code with their own network and data boundaries.\n\nTelemetry is disabled in the controlled fleet profile. Enabling CrewAI or\nOpenTelemetry tracing requires a separate review of content, credential, and\ndestination exposure.\n\nIsolate tenants and active processes\n\nUse one connector instance for one reviewed tenant, descriptor set, registry,\nsidecar token, and durable sidecar state boundary. Deployment metadata may\nalso record an external account, but the reviewed CrewAI host does not compare\nthat label with a descriptor ID automatically.\n\nOnly one active sidecar process may own a state journal. Horizontal scaling\nuses independent connector instances with independent state volumes, tokens,\nreplica identities, and routes.\n\nDo not mount one journal into active replicas. The local file lock is a\nsingle-writer process fence, not a distributed coordinator.\n\nRotate without splitting the boundary\n\nThe host and sidecar load their authentication and admission inputs at startup.\nTreat rotation as a coordinated replacement rather than an undocumented live\nreload.\n1. freeze new unsafe assignment to the affected instance;\n2. inventory running jobs and preserve their Action IDs and journal owner;\n3. create a new token file and, when needed, a reviewed descriptor or registry\n   revision;\n4. start a replacement sidecar against a new or deliberately transferred\n   state boundary;\n5. start its matching Rust host with the same new token and fixed origin;\n6. require authenticated health, descriptor agreement, and expected discovery;\n7. route new Actions only after those checks pass;\n8. drain the old instance before revoking its token or removing its state;\n9. retain redacted identity and transition evidence.\n\nNever let an old host authenticate to a new sidecar unintentionally. Never\ndelete a journal while a job outcome may still be uncertain.\n\nDiagnose boundary failures\n\n| Symptom | Decision |\n\n| Host rejects the token | Check file type, permissions, UTF-8, length, and prohibited characters without printing it |\n| Sidecar returns 401 | Compare the mounted token sources and restart ownership; do not put the value in a diagnostic command |\n| Sidecar refuses startup without a token | Configure the protected file, or bind loopback and enable the explicit development exception |\n| Descriptor is rejected | Check file count and size, non-empty IDs and names, ID controls, uniqueness, capability syntax, and operation sets |\n| Registry fails to load | Verify module:attribute, importability, mapping shape, IDs, and factory or clone behavior |\n| Host is healthy but not ready | Compare admitted crew IDs and operations with authenticated sidecar health |\n| A crew is present only in the registry | Add a reviewed host descriptor and admission policy before exposing it |\n| Provider returns an authentication error | Investigate the crew-owned model, tool, or provider credential, not the sidecar token |\n| Data appears across tenant boundaries | Disable routing and reconcile tenant, instance, descriptor, registry, state volume, and provider authority |\n\nPreserve Action ID, tenant, instance, replica, descriptor revision, sidecar\nartifact, registry identity, credential revision, and redacted error category.\nDo not retain token bytes or raw model and tool content by default.\n\nRelated documentation\n• CrewAI connector overview (../README.md)\n• Run the CrewAI 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": "25345361c7ac6bbce7e9e9534e2a76680355d019b179241e3b0688bd5069e254"
  }
}