Syncing entities
Policies are only as good as the data they evaluate over. The entity store holds your principals, resources, attributes, and relationships — and the ingestion API keeps it in step with your systems of record (your user database, your HR system, your resource catalog).
All ingestion happens through the Control Plane API; changes reach your Policy Decision Points automatically within one sync cycle, including deletions.
Authentication
Section titled “Authentication”Ingestion uses an app token with entities permissions, ideally project-scoped. Create one in the Console (or via the API) with:
entities: writefor batch upserts and validation (readtoo if your job reads entities back);entities: deleteas well for any batch that containsdeleteoperations, and always for reconcile, since a reconcile can delete.writealone cannot destroy data.
Send it as Authorization: Bearer <app-token>. Ingest endpoints accept app tokens only (not Console sessions) and are rate-limited to 120 requests per minute per token.
The entity shape
Section titled “The entity shape”Entities use the standard Cedar JSON form:
{ "uid": { "type": "App::User", "id": "alice" }, "attrs": { "email": "alice@example.com", "department": "engineering" }, "parents": [ { "type": "App::Team", "id": "engineering" } ]}parents is what powers principal in App::Team::"engineering" checks in your policies.
Batch: incremental changes
Section titled “Batch: incremental changes”POST /projects/entities/batch applies up to 250 operations per request, each one of:
| Operation | Effect | Retry-safe? |
|---|---|---|
create |
Insert; fails if the entity exists | Yes |
overwrite |
Insert or replace whole entity | Yes |
update |
JSON-Patch an existing entity | No — patches aren’t idempotent; prefer overwrite |
delete |
Tombstone the entity | Yes |
The response reports per-item results (successCount, failureCount, and an error per failed item), so a partially valid batch doesn’t force you to resubmit everything.
Use batch for event-driven sync: a user joins, a document is created, a team membership changes — push the delta as it happens.
Reconcile: declarative full state
Section titled “Reconcile: declarative full state”POST /projects/entities/reconcile takes the complete desired set of entities (up to 5,000 entities per request, within the API’s 5 MB request-body limit) and computes the diff for you:
- entities absent from your set are deleted;
- changed entities are overwritten;
- unchanged entities are untouched;
- new entities are created.
Scoped reconcile
Section titled “Scoped reconcile”By default, reconcile treats your set as the entire project: entities of any type missing from it are deleted. If your source of truth owns only some entity types (say, users and teams from your HR system, while documents come from elsewhere), pass a scope:
{ "scope": { "entityTypes": ["App::User", "App::Team"] }, "entities": [ … ]}Only entities of the listed types are compared and deleted. Everything else in the project is left alone. Every entity you send must be of a listed type, otherwise the request is rejected with 400.
The request applies atomically. Sending an empty set is refused unless you explicitly pass confirmEmpty: true — a guard against accidentally mass-deleting a project’s entities with an empty export.
Use reconcile for periodic full syncs (a nightly job from your source of truth) or as a self-healing pass on top of event-driven batches.
Validate before you push
Section titled “Validate before you push”POST /projects/entities/validate checks a set of entities against the project’s active schema without writing anything — wire it into CI for your sync job so schema drift is caught before it lands.
Propagation
Section titled “Propagation”- Writes land in the versioned entity store immediately and reach every attached PDP within one sync cycle (~20 seconds).
- Deletions propagate on the same schedule — a removed entity stops matching policies within seconds, not at the next full resync.
- The store is append-only and versioned, so ingestion never destroys history.