Security Rules

Rules decide who may read and write each part of your database. They are evaluated on every request from a client SDK, using the identity of the user making it — reads, queries, listeners, writes and batches alike.

1Rules anatomy#

How they combine:

• Any rule that allows, allows. The root, every level on the way down and both the general and the specific key at a level (.read and .get) are checked; one that holds is enough. No rule that holds = denied.
• Every .validate on the path must hold, from the root down, for add(), set(), update() and every write in a batch.
• A create is a write to a document that doesn't exist yet (data is null); a delete is a write with newData null; anything else is an update.

2Example ruleset#

{
  "rules": {
    "posts": {
      ".read": true,
      ".write": "auth.uid === 'editor-1'"
    },

    "notes": {
      "$noteId": {
        ".get": "data.ownerId === auth.uid",
        ".list": "data.ownerId === auth.uid",
        ".create": "newData.ownerId === auth.uid",
        ".update": "data.ownerId === auth.uid && newData.ownerId === auth.uid",
        ".delete": "data.ownerId === auth.uid",
        ".validate": "newData.hasChildren(['title'])"
      }
    },

    "users": {
      "$userId": {
        ".read": "auth.uid === $userId",
        ".write": "auth.uid === $userId"
      }
    }
  }
}

Save rules in the Abrova Console under your database. The Console checks them as you type, and refuses to publish a rule that can't be read (a typo, an unknown function, a $name that isn't on its path).

3Queries and listeners: rules are not filters#

A query or a listener is allowed only when the rules allow every document it could return. If they don't, the whole query is refused — it is never quietly trimmed to the documents you may see.

The rules are checked against the query itself: a field the query compares with == (or in, up to 10 values) is known, any other field is not. So with the notes rules above:

A refused query fails with 403 query_not_allowed; the error names the fields the rules read, so you know what to filter on. Filters the rules don't mention (ranges, !=, sorting, limits) only narrow the results and never stop a query that is otherwise allowed. Rules can also read request.query.limit to cap page sizes.

A rule that needs the document's own id (auth.uid === $userId) can't allow a query — the query doesn't have one. Such rules suit .get; give .list a rule on a field instead.

4Teams, groups and roles: rules that look up documents#

Rules can read other documents of the same database:

Build the path from text written in the rule and values joined with +: $wildcards, auth.uid, document fields. A value can only ever be one id — a value with / in it, or an empty one, makes the lookup fail and the rule deny — so data a user chose can't point the lookup at another collection.

A team with members and roles, kept by your app alone (no server needed):

{
  "rules": {
    "teams": {
      "$teamId": {
        ".get": "exists('team_members/' + $teamId + '_' + auth.uid)",
        ".create": "newData.createdBy === auth.uid",
        ".update": "get('team_members/' + $teamId + '_' + auth.uid).data.role === 'admin'",
        ".delete": "get('team_members/' + $teamId + '_' + auth.uid).data.role === 'admin'"
      }
    },
    "team_members": {
      "$memberId": {
        ".read": "data.userId === auth.uid || exists('team_members/' + data.teamId + '_' + auth.uid)",
        ".create": "$memberId === newData.teamId + '_' + newData.userId && ((newData.userId === auth.uid && newData.role === 'admin' && !exists('teams/' + newData.teamId) && getAfter('teams/' + newData.teamId).data.createdBy === auth.uid) || get('team_members/' + newData.teamId + '_' + auth.uid).data.role === 'admin')",
        ".update": "get('team_members/' + data.teamId + '_' + auth.uid).data.role === 'admin' && newData.teamId === data.teamId && newData.userId === data.userId",
        ".delete": "data.userId === auth.uid || get('team_members/' + data.teamId + '_' + auth.uid).data.role === 'admin'"
      }
    },
    "lists": {
      "$listId": {
        ".read": "exists('team_members/' + data.teamId + '_' + auth.uid)",
        ".create": "get('team_members/' + newData.teamId + '_' + auth.uid).data.role in ['admin', 'editor']",
        ".update": "newData.teamId === data.teamId && get('team_members/' + data.teamId + '_' + auth.uid).data.role in ['admin', 'editor']",
        ".delete": "get('team_members/' + data.teamId + '_' + auth.uid).data.role in ['admin', 'editor']"
      }
    }
  }
}

• Create a team in one batch: the team document and its creator's admin member document (<teamId>_<userId>). getAfter() sees the team the same batch creates; !exists(…) makes sure it is new.
• Members read their team with queries that filter on what the rules check: team_members where teamId == T (allowed for members of T) or where userId == <me> ("my teams"), lists where teamId == T.
• Nobody moves a document to another team: .update requires teamId to stay the same.
• Removing a member takes effect at once, also for that member's open listeners (SDK 0.3.0 and later): they are checked again and end.
• Invites: add an invitations collection whose documents the invited user marks used in the same batch that creates their member document, and check it with get() / getAfter(). Use long random invite ids (at least 128 bits) and give invitations a .get rule but no .list, so they can't be listed.

A batch is checked and saved as one: two people using the same invite at the same moment can't both get in, and a member removed a moment before can't still write.

Limits and cost

• At most 10 documents looked up per request or query, 20 per batch (and 10 per operation in it). Beyond that the request is denied.
• Each document looked up is read once per request and billed as a document read.
• Lookups read only the same database, and are not themselves subject to rules.

5Where auth.uid comes from#

Rules are only as trustworthy as the identity behind them. Your API key is public — it ships inside every app bundle — so it cannot decide who the user is.

Your backend mints a user token with the server secret and hands it to your app:

// Your backend, behind your own session check
const response = await fetch('https://sync.abrova.ir/users/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.ABROVA_API_KEY,
    'x-server-secret': process.env.ABROVA_SERVER_SECRET,
  },
  body: JSON.stringify({ userId: session.userId }),  // your id for the user
});

const { token, expiresIn } = await response.json(); // expiresIn: 3600 by default

Every SDK takes it through a token provider and refreshes it before it expires — see Initialization. With Abrova Auth your app gets this token without a server of its own.

One token for every Abrova product

If your app also uses Abrova Chat, Abrova Push or Abrova A/B Testing, mint one token for all of them from the Abrova auth endpoint instead:

curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "2026-09-21T10:00:00.000Z" }

Give that same token to every SDK's tokenProvider — Sync, Chat, Push and A/B Testing. expiresIn is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum. Call it from your server, never from an app.

Custom claims (roles)

Your server can add facts about the user to the token it mints — a role, a membership level, the teams they belong to. Rules read them as auth.token.<name>, and a string role claim is also available as auth.role:

body: JSON.stringify({ userId: session.userId, claims: { role: 'admin', membership: 'gold', teams: ['red'] } }),

".write": "auth.role === 'admin' || auth.token.teams.includes('red')"

Both token endpoints accept claims: up to 20 names (letters, digits and _), each a text of up to 256 characters, a number, true / false, or a list of up to 50 texts — 1 KB in all. Reserved token names (sub, exp, iat, …) are refused. Claims are signed into the token, so an app can neither add nor change them; a user whose token has no such claim fails the check. Mint a new token when a user's role changes — or keep roles in documents and look them up (step 4), which needs no new token.

How the user signed in

With Abrova Auth, auth.amr says how the user signed in: anonymous, apple, google, password, magic_link or telegram. auth.anonymous is true only for a guest — use auth.anonymous === false to keep guests out of shared data. A token your server mints names a real user: it has no auth.amr, and auth.anonymous is false.

Signing a user out everywhere

In the Console, Sync › Security › Sign a user out everywhere refuses every token issued to that user before that moment, including live connections and listeners. Their apps get 401 token_expired, ask your server for a new token through the token provider, and get one only if your server still issues it.

An app where no one is signed in yet has no token to send. The client SDKs (0.2.1 and later) handle that for you: the connection waits and the SDK connects after sign-in — see Initialization.

6Expression reference#

How they behave:

• == is the same as ===: values are never converted, so 5 does not equal '5'.
• A field the document does not have counts as null.
• Errors deny. Some expressions can't be decided: a comparison with an auth value that is missing (no user, no such claim), < on something that isn't a number, get() of a document that doesn't exist, a field of a query document the query doesn't filter on. Such a part is neither true nor false: error || true still allows, error && false is false, !error stays an error, and a rule that ends in an error denies. So neither data.ownerId !== auth.uid nor !(data.ownerId === auth.uid) lets a request without a user in.
• A field used on its own as a condition (data.public) must be true or false.

7Who is not subject to rules#