Skip to main content

Data Access Control Concepts

Fluree's access control system lets you define exactly who can see and modify what data — not at the API layer, but at the data layer itself. This guide explains the concepts. When you're ready to write policies, head to Writing Policies.

Data-Centric Security​

Most databases rely on application perimeters for security: APIs, firewalls, and middleware standing between users and data. If you breach the perimeter, the data is exposed.

Fluree takes a different approach: the data defends itself. Access policies live in the ledger alongside your data and are evaluated at query time, not in your application. This means:

  • You can safely expose Fluree directly without building an intermediary API layer
  • Multiple applications can share the same data, all governed by the same policies
  • Security travels with the data — not with whatever service happens to sit in front of it

How It Works​

1. Identity​

When you make a request to Fluree, you identify yourself with a DID (Decentralized Identifier) — a unique, cryptographic identifier that proves who's making the request:


did:fluree:Tf5Z5F4u8nmccw2cmhYxfpSPAbpi8yoVBFZ

2. Policy Class​

Your DID gets linked to one or more policy classes — each a label you define that groups related policies together:


{
"@id": "did:fluree:Tf5Z5F4u8nmccw2cmhYxfpSPAbpi8yoVBFZ",
"f:policyClass": {"@id": "UserPolicyClass"}
}

3. Policies​

Policies that share your class name define what you can access — which actions are allowed and under what conditions:


{
"@id": "policy/readOwnData",
"@type": ["Policy", "UserPolicyClass"],
"f:action": [{"@id": "f:view"}],
"f:query": {
"@type": "@json",
"@value": {
"where": {"@id": "?$this", "ex:owner": "?$identity"}
}
}
}

4. Filtered Results​

When you query, Fluree evaluates all applicable policies and returns only the data you're permitted to see. Restricted data isn't redacted — it's simply absent, as if it doesn't exist.

Policy Classes​

Policy classes group related policies together. Identities are then assigned to one or more classes, and Fluree applies all policies in those classes. The names are yours to choose — here are some common patterns:

Policy Class examplesPurpose
RootPolicyClassFull access to all data (superuser)
UserPolicyClassScoped access based on user identity
PublicPolicyClassUnauthenticated/public read access
AuditorPolicyClassRead-only access to everything

What Policies Can Control​

Because policies use the same query engine as everything else in Fluree, they can reach any data in your ledger — which means anything you can query, you can control. Here are some examples of the kinds of rules you can express:

  • Which entities you can see — only your own records, or records related to you
  • Which entity types — different rules for different types of data (e.g., shipments vs. users)
  • Read vs. write — read anything, write only your own data

Context-Aware Rules​

Because policies can query the current state of your data, your access rules can be as sophisticated as your data model. For example:

  • "Users can only edit shipments that haven't been delivered yet"
  • "Employees can see shipments associated with their location"
  • "Admins can view and modify everything"

Fluree evaluates these conditions in real-time against live data — no application logic required.

Example: User Can Only See Their Own Records​

Here's how it all fits together:

  1. Alice authenticates with her DID
  2. Her DID is linked to UserPolicyClass and to her user record user/alice
  3. A policy for UserPolicyClass says "you can only view entities you own"

When Alice queries all records:

  • She sees her own data
  • Bob's records are filtered out entirely — not redacted, but as if they don't exist

Policy as Data​

Policies are stored as ordinary data in your ledger, which means they get all the same capabilities as everything else:

  • Transactions — add, update, or remove policies just like any other data
  • Queries — inspect your current policies at any time
  • History — audit who changed what policy and when
  • Access control — you can even write policies that govern who is allowed to modify policies

Next Steps​