Skip to Content
AeroSearch Docs
Guides

Map visible_by to Document ACLs

Turn a source visible_by attribute into Document allow and deny principals so alice's end-user token sees the Document and bob's does not.

A source record often carries who may see it as a visible_by attribute. Write those values onto the Document ACL when you push the Document. The Identity Graph turns a provisioned identity into a Principal. A verified end-user token expands to that Principal. Deny overrides allow.

visible_by is not itself an ACL. The ingest API accepts allow_users, allow_groups, deny_users, and deny_groups. Map the attribute before the push.

Register the signing key

Register one ES256 public key on the Project. A second key can be active during rotation. The Cell picks up the ConfigBundle without a restart. Keep the private key on your side and use it only to mint tokens.

Provision the identity

Create the Identity Graph node for each person who should match visible_by. An authored ref looks like okta:user:alice. An unknown ref is rejected at batch accept with acl_unresolved on that line. The other lines can still be accepted.

Map the attribute

Source attributeDocument ACL
visible_by user refsacl.allow_users
visible_by group refsacl.allow_groups
hidden_from user refsacl.deny_users
hidden_from group refsacl.deny_groups

A record visible_by: ["okta:user:alice", "okta:group:finance"] and hidden_from: ["okta:user:bob"] becomes:

{
  "op": "upsert",
  "doc": {
    "external_id": "policy-17",
    "title": "Refund policy",
    "acl": {
      "allow_users": ["okta:user:alice"],
      "allow_groups": ["okta:group:finance"],
      "deny_users": ["okta:user:bob"],
      "allow_anonymous": false
    }
  }
}

Push that line to POST /v1/collections/{collection}/documents:batch. Alice's token sees the Document. Bob's token does not. If deny_users also names alice, the Document is hidden from alice even though allow_users names her.

Mint the end-user token

Sign with ES256 and the private key for the registered public key. Set aud to the Project id, sub to a pseudonym, idp_subject to the authored ref (okta:user:alice), and token_groups to values that already start with token:group:. exp minus iat must be at most 60 minutes. Send the token on X-AeroSearch-End-User-Token with the Project search API key.

The TypeScript server helper is mintEndUserToken. The Python helper is aerosearch_sdk.end_user_token.mint_end_user_token. Neither helper accepts an HMAC secret.

A verified token whose idp_subject is a valid user reference with no Identity Graph node keeps that user's stable tenant-scoped principal in both the allow set and the deny set, with no group expansion. A user-level deny still hides an anonymous Document. The JWT sub is not authorization. A tombstoned subject expands to no principals. An Identity Graph outage fails the search closed. A token:group: value the graph does not know grants nothing.

On this page