Document-level access controls

Custom data sources optionally support document-level access control. Unlike crawled connectors, a custom data source has no native permission system, so you supply the access control list (ACL) for each document when you ingest it with the IngestKnowledgeBaseDocuments operation. For the overview of ACL awareness across all connectors, see Access Control Lists awareness enablement.

How it works

For an ACL-enabled custom data source, Bedrock Managed Knowledge Base applies the customer-provided access control lists during pre-retrieval filtering, returning only documents the querying user is permitted to access. Real-time ACL verification is not supported for custom data sources because the customer-provided ACL metadata is the source of truth.

Enable ACL awareness

To enable ACL awareness for a custom data source, set aclEnabled to true in the connectorParameters when you create or update the data source. For the data source configuration structure, see Custom.

"connectorParameters": {
    "type": "CUSTOM",
    "version": "1",
    "aclEnabled": true
}

Provide access controls when you ingest documents

You provide a document's ACL through the accessControlList field on the document's metadata in the IngestKnowledgeBaseDocuments request. The ACL source is determined by metadata.type, the same field that controls where metadata attributes come from:

Because accessControlList lives under metadata rather than as a top-level field on KnowledgeBaseDocument, a document has a single ACL source, controlled by metadata.type. This prevents conflicting ACLs from being supplied for the same document (for example, an inline ACL on the request and an ACL in the S3 file). The tradeoff is that you cannot mix an inline ACL with S3-based metadata attributes, or S3-based ACL with inline metadata attributes, for the same document.

Each accessControlList entry contains:

Inline ACL (metadata.type = IN_LINE_ATTRIBUTE)

Supply the accessControlList directly in the request body alongside the inline metadata attributes.

PUT /knowledgebases/KB12345678/datasources/DS12345678/documents HTTP/1.1
Content-type: application/json

{
    "documents": [
        {
            "content": {
                "dataSourceType": "CUSTOM",
                "custom": {
                    "customDocumentIdentifier": {
                        "id": "hr-policy-2026"
                    },
                    "inlineContent": {
                        "textContent": {
                            "data": "Annual leave policy: All full-time employees are entitled to..."
                        },
                        "type": "TEXT"
                    },
                    "sourceType": "IN_LINE"
                }
            },
            "metadata": {
                "type": "IN_LINE_ATTRIBUTE",
                "inlineAttributes": [
                    {
                        "key": "department",
                        "value": { "stringValue": "HR", "type": "STRING" }
                    }
                ],
                "accessControlList": [
                    {
                        "name": "alice@example.com",
                        "type": "USER",
                        "access": "ALLOW"
                    },
                    {
                        "name": "bob@example.com",
                        "type": "USER",
                        "access": "DENY"
                    }
                ]
            }
        }
    ]
}

S3-based ACL (metadata.type = S3_LOCATION)

Point the document's metadata at a .metadata.json file in Amazon S3. Both the metadata attributes and the accessControlList are read from that file.

"metadata": {
    "type": "S3_LOCATION",
    "s3Location": {
        "uri": "s3://amzn-s3-demo-bucket/hr-policy-2026.metadata.json"
    }
}

The .metadata.json file uses the same format as the per-document metadata files for Amazon S3 data sources. This file uses capitalized ACL field names (Name, Type, Access), which differ from the lowercase field names (name, type, access) used in the inline request.

{
    "metadataAttributes": {},
    "accessControlList": [
        {
            "Name": "alice@example.com",
            "Type": "USER",
            "Access": "ALLOW"
        },
        {
            "Name": "bob@example.com",
            "Type": "USER",
            "Access": "DENY"
        }
    ]
}

Verify your configuration

Because Custom ACLs are customer-provided through IngestKnowledgeBaseDocuments, validate them before you query:

Troubleshooting