Index document ACLs with the push REST APIs

Note

Foundry IQ (Azure AI Search) provides direct indexing and query APIs alongside higher-level knowledge source and knowledge base APIs for managed retrieval. Use the Azure portal, REST APIs, or Azure SDKs to configure these capabilities, or connect agents to knowledge bases in the Microsoft Foundry portal.

Document-level permission ingestion through the push REST APIs is generally available. Use the push REST APIs to index content with Microsoft Entra user and group IDs or storage container RBAC scopes. Foundry IQ (Azure AI Search) uses this metadata to filter documents at query time.

Key features include:

  • Flexible control over ingestion pipelines.
  • Standardized schema for permissions metadata.
  • Support for hierarchical permissions, such as folder-level ACLs.

This article explains how to use the push REST API to index document-level permission metadata in Foundry IQ. This process prepares your index to query and enforce end-user permissions on search results.

Prerequisites

  • Content with ACL metadata from Microsoft Entra ID or another POSIX-style ACL system. For userIds and groupIds ACL fields, use Microsoft Entra object IDs (GUIDs), not UPNs or email addresses. Stable object IDs ensure reliable identity matching at query time, even if directory attributes change.

  • REST API version 2026-10-01.

  • An index schema with permissionFilterOption enabled, plus permissionFilter field attributes that store document permissions.

  • Existing permission to create the index definition, upload documents, and query the index. For role-based access, see Connect using roles.

  • For the query examples, a delegated user access token and the same user's Microsoft Entra object ID. See Query-time token roles and permission flows.

Limitations

  • An ACL field with permission filter type userIds or groupIds can hold at most 1000 values.

  • An index can hold at most five distinct rbacScope values across all documents.

  • Native permissionFilter annotations can be added to or removed from existing compatible fields. An existing annotation can't be changed directly to a different permission filter type.

  • Only one field of each permissionFilter type (one each of groupIds, userIds, and rbacScope) can exist in an index.

  • Each permissionFilter field must be filterable and top-level. It must not be a key or vector field. Permission fields can't have analyzers, normalizers, or synonym maps.

  • Query-time permission enforcement reflects the ACL values last written to the index. If source permissions change, those updates aren't reflected until you reingest or update the affected documents. Schedule incremental reingestion or partial updates to keep ACLs current.

  • This functionality is currently not supported in the Azure portal.

Create an index with permission filter fields

Indexing document ACLs and RBAC metadata with the REST API requires setting up an index schema that enables permission filters and has fields with permission filter assignments.

Set permissionFilterOption explicitly to enabled. Valid values are enabled and disabled. On a new index with permission field annotations, omitting the option defaults it to enabled. On an update, omission preserves an existing option when present.

Use Collection(Edm.String) for userIds and groupIds, and Edm.String for rbacScope. An index can have one field of each annotation type.

The following 2026-10-01 workflow creates a separate example index with a userIds permission field. The searchable content field also supports the moreLikeThis examples. Replace <SEARCH_SERVICE_ENDPOINT> with your endpoint and <SEARCH_ACCESS_TOKEN> with a caller token that has the required Search roles. Use the example name only for a new index because the request updates an existing index with the same name.

PUT <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json

{
  "name": "secured-content-index",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "filterable": true,
      "sortable": true
    },
    {
      "name": "content",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "category",
      "type": "Edm.String",
      "searchable": false,
      "filterable": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "userIds",
      "type": "Collection(Edm.String)",
      "filterable": true,
      "retrievable": false,
      "searchable": false,
      "sortable": false,
      "facetable": false,
      "permissionFilter": "userIds"
    }
  ],
  "permissionFilterOption": "enabled"
}

Reference: Create or Update Index.

The following 2026-10-01 schema fragment illustrates all three native permission field types for the indexing example later in this article:

{  
  "fields": [  
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false },
    { "name": "DocumentId", "type": "Edm.String", "key": true }  
  ],
  "permissionFilterOption": "enabled"
}

For enterprise repositories, such as SharePoint Online, resolve document-level or folder-level permissions to Microsoft Entra user and group object IDs during ingestion before calling the push API. You should then store those IDs in the corresponding permission fields.

Establish trusted document identity and grants

Restrict document publishing to identities authorized to maintain the target content and permissions. The publisher must obtain grants from an authoritative access policy for the same document identity, rather than copying permission-like properties from ordinary content.

Review the document key and permissions together before submitting an upload or merge. Reusing a key targets the same indexed record; permission to write content isn't by itself authority to change another record's content or grants. When multiple trusted sources intentionally share a record, agree on its ownership and final permission policy. A merge replaces a supplied collection rather than combining its entries with existing values.

For a customer-managed pipeline, control which source value supplies DocumentId and which policy supplies grants for that identity. Keep business identifiers separate if they aren't unique across the contributing sources. Don't let lower-trust content select another record's key or permission values. These responsibilities belong to the authorized publisher, not a new ownership-enforcement setting.

The permission-field annotations enable query evaluation of stored values; they don't establish that a content author is authorized to supply those grants. Use the ingestion configuration checklist to keep identity and permission selection within the trusted publishing process.

REST API indexing example

Populate permission fields like other document fields. For the 2026-10-01 index you created earlier, upload the following four documents. Replace <USER_OBJECT_ID> with the Microsoft Entra object ID of the delegated user whose token you supply in the query example. Documents 21, 101, and control grant that user access; hidden has no grant.

POST <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')/docs/search.index?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json

{
  "value": [
    {
      "@search.action": "upload",
      "id": "21",
      "content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
      "category": "astronomy",
      "userIds": [
        "<USER_OBJECT_ID>"
      ]
    },
    {
      "@search.action": "upload",
      "id": "101",
      "content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
      "category": "astronomy",
      "userIds": [
        "<USER_OBJECT_ID>"
      ]
    },
    {
      "@search.action": "upload",
      "id": "hidden",
      "content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
      "category": "astronomy",
      "userIds": [
        "none"
      ]
    },
    {
      "@search.action": "upload",
      "id": "control",
      "content": "Botanical gardens cultivate orchids and roses. Gardeners prune flowering plants and water their roots. A greenhouse protects young seedlings from cold weather.",
      "category": "gardening",
      "userIds": [
        "<USER_OBJECT_ID>"
      ]
    }
  ]
}

Reference: Index Documents.

Continue with the query example to confirm that the user's documents are returned while hidden is excluded.

The following 2026-10-01 example illustrates the other options.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-10-01
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["none"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

Update ACLs pushed before the October 2026 normalization change

Foundry IQ normalizes permission ID values to lowercase when you submit documents. This behavior applies to fields annotated with permissionFilter: "userIds" or permissionFilter: "groupIds", but it doesn't apply to the field names or unrelated document fields.

An October 2026 service update introduces this normalization for 2026-05-01-preview and 2026-08-01-preview. This change continues in the 2026-10-01 GA REST API. The service doesn't automatically rewrite previously stored values. Changing the API version alone doesn't update them.

If you directly pushed ACLs by using either preview version before the normalization change, existing uppercase or mixed-case permission IDs can fail to match query-time identities. Authorized users might receive fewer results than expected.

This migration applies only to ACLs submitted directly through the Push API. It isn't required for built-in indexers or indexed knowledge sources.

To reindex affected ACL values:

  1. Identify documents and chunks with permission IDs pushed before the change. Values already stored in lowercase don't need this casing update.
  2. Resubmit the current ACL values for every affected record. Use a merge action with its document key and complete permission collections to update ACLs without replacing content. A merge replaces the supplied collection; include every current grant, not just entries whose casing changed.
  3. Check each record's indexing response and retry failed updates. Continue until you update all affected records. A partial migration can leave inconsistent matching.
  4. Test queries as a user who should have access and a user who shouldn't. Use elevated read only for diagnostics, not to expose ACL values in ordinary user results.

ACL access resolution rules

Native permission filtering evaluates userIds, groupIds, and rbacScope as alternative grants, combined with OR. A match in any one field grants document access; a nonmatch in another field doesn't override that grant. This any-grant behavior requires successful permission evaluation.

A user gains access through a matching user or group ID, or storage blob-read authorization on the indexed container scope. Storage scope checks use the delegated user in x-ms-query-source-authorization, not the operation credential. Operation authorization is still required. For details and permission-evaluation failure behavior, see Query-time ACL and RBAC enforcement.

Special ACL value "none"

ACL fields, such as userIds and groupIds, typically contain Microsoft Entra object IDs (GUIDs) that identify users and groups with access to the document. Use the special string value none or an empty array to indicate that an ACL field doesn't grant access.

ACL value Meaning
["none"] No user can access the document by matching this ACL type
[] (empty array) No user can access the document by matching this ACL type

Setting userIds to ["none"] or an empty array means no users are granted access to the document based on user ID. They might still be granted access by matching group ID or RBAC metadata.

Access control example

This example illustrates how document access rules are resolved based on permission field values in userIds, groupIds, and rbacScope. For readability, this scenario uses aliases such as "user1" and "group1" instead of GUIDs; in production, use Microsoft Entra object IDs (GUIDs).

Document # userIds groupIds RBAC Scope Permitted users list Note
1 ["none"] [] Empty No users have access The values ["none"] and [] behave exactly the same
2 ["none"] [] scope/to/container1 Users with RBAC permissions to container1 The value of "none" doesn't block access when other permission fields (groupIds or rbacScope) grant access
3 ["none"] ["group1", "group2"] Empty Members of group1 or group2
4 ["user1", "user2"] ["group1"] Empty User1, user2, or any member of group1
5 ["user1", "user2"] [] Empty User1 or user2