Skip to content

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.

Ingestion uses an app token with entities permissions, ideally project-scoped. Create one in the Console (or via the API) with:

  • entities: write for batch upserts and validation (read too if your job reads entities back);
  • entities: delete as well for any batch that contains delete operations, and always for reconcile, since a reconcile can delete. write alone 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.

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.

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.

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.

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.

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.

  • 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.