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 attribute | Document ACL |
|---|---|
visible_by user refs | acl.allow_users |
visible_by group refs | acl.allow_groups |
hidden_from user refs | acl.deny_users |
hidden_from group refs | acl.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.