docs: explain indexAllocator for status updates

index.html

@@ -3765,6 +3765,38 @@ <h5>Update Status</h5>
 list credential accordingly.
       </p>
 
+      <p>
+Issuer instances are responsible for assigning one or more status entries to
+the Verifiable Credentials they issue. Issuer software is expected to ensure
+that it does not overallocate or misallocate status metadata (e.g., status
+lists or list indexes), as this overallocated, misallocated, or unused
+information can create privacy harms both to holders and issuers of Verifiable
+Credentials. In architectures that are highly available, horizontally scalable,
+or distributed, or any combination of these, this can can be especially
+challenging unless status allocation state is appropriately shared, identified,
+and referenced across disparate components. The `indexAllocator` field can be
+used to identify and refer to shared state, allowing for better coordination
+as well as atomic allocation and use of status metadata.
+      </p>
+      <p>
+Status mechanisms associate each [=verifiable credential=] with a
+<code>statusListIndex</code> in a list (see, for example, the [[[VC-BITSTRING-STATUS-LIST]]] specification).
+Implementations that assign those indices usually track which values are in use so
+indices are not reused incorrectly and status updates modify the correct entry. When a
+status service supports more than one such tracker—such as separate allocators per
+tenant, deployment, or <code>statusPurpose</code>—the optional <code>indexAllocator</code>
+request field names which allocator context applies to this update. The same identifier
+would typically have been fixed or returned when the index was originally assigned at
+issuance (or when the list was provisioned), so issuance and status-update flows stay
+consistent even though list creation and credential issuance are separate API surfaces
+in this specification.
+      </p>
+
+      <p class="note" title="indexAllocator values">
+Permitted <code>indexAllocator</code> strings are implementation-defined; this
+specification does not mandate particular values or a discovery mechanism for them.
+      </p>
+
       <div class="api-detail"
         data-api-endpoint="post /credentials/status"></div>
     </section>

oas.yaml

@@ -804,7 +804,10 @@ components:
       type: object
       required: ['credentialId', 'credentialStatus', 'status']
       additionalProperties: false
-      description: Credential status information to be updated.
+      description: >-
+        Credential status information to be updated. When a deployment runs more than one
+        mechanism that assigns or records `statusListIndex` values, an optional
+        `indexAllocator` can identify which allocator context to use (see that property).
       properties:
         credentialId:
           type: string
@@ -830,12 +833,24 @@ components:
           description: Specifies the new status.
         indexAllocator:
           type: string
-          description: For services to use which indexes are being used/assigned to VCs.
+          description: >-
+            Optional identifier for the index-allocation context the status service should
+            use for this request. Status mechanisms such as bitstring status lists associate
+            each credential with a `statusListIndex` inside a list; implementations often keep
+            internal bookkeeping (free lists, counters, per-tenant pools, etc.) so indices are
+            not double-assigned and updates target the correct row. When multiple allocators
+            exist—for example, separate pipelines per tenant, environment, or
+            `statusPurpose` — `indexAllocator` tells the service which registry or policy to
+            consult or update alongside `credentialId` and `credentialStatus`. Omission is
+            allowed when the implementation infers a single default allocator or when
+            `credentialStatus` already fully identifies the list entry. Allowed values are
+            implementation-specific; this specification does not define a registry of names.
       example:
         {
           "credentialId": "0fc754bc-fc32-46a0-aec1-a5ef385e7ea0",
           "credentialStatus": { "type": "BitstringStatusList", "statusPurpose": "revocation" },
-          "status": True
+          "status": true,
+          "indexAllocator": "tenant-acme-revocation"
         }
     CreateStatusListRequest:
       type: object