Skip to content
excalibase
rls
GraphQL APIstable

Permissions and Row-Level Security

Excalibase decides what a caller may reach the way Hasura does, and applies the same rules to GraphQL, REST and realtime:

  • Every request runs as exactly one role.
  • A table a role has no permission for does not exist for it: it is not in the role's GraphQL schema, REST answers 404, and realtime refuses the subscription.
  • A permission is one object per table, role and operation (select, insert, update, delete). It says which rows (a boolean expression over the row), which columns, and, for writes, what the new row must satisfy.
  • A database function is reachable only when the project tracks it, and then only by roles allowed to call it.

Nothing is reachable until you permit it. A table with no permission for anon is not readable without a key; a project owner opts a table in.

On Excalibase Cloud

Roles

RoleWho
anonA request with no token, or a token from a publishable key.
userA signed-in end user: the default role Auth gives accounts.
any other nameA custom role carried by the token's role claim, for example editor.
serviceA token from a secret key. It bypasses permissions: keep it on servers.

A publishable key (esk_pub_...) only ever grants what anon is granted, which is why it is safe to ship in a page. A token's role claim is its default role and allowed_roles lists the roles it may act as; the X-Excalibase-Role header picks one of them.

Set permissions

In Studio, open Database > Tables and set the API permissions for a table and role. The same permissions can be set from the MCP tools list_permissions and set_permission, or the control plane API. One permission object looks like this:

{
  "table": "public.kanban_cards",
  "role": "user",
  "select": {
    "filter": { "owner_id": { "_eq": "X-Excalibase-User-Id" } },
    "columns": ["id", "board_id", "title", "status", "position"]
  },
  "insert": {
    "check": {},
    "columns": ["board_id", "title", "status", "position"],
    "set": { "owner_id": "X-Excalibase-User-Id" }
  }
}
  • filter is ANDed into every read of the table, including nested reads, cursors and counts.
  • columns lists what the role may read or write.
  • set fills a column from the caller (here the signed-in user's id) and the client cannot send it.
  • check must hold for a written row, or the write is refused with 403 permission_check_failed.
  • limit caps the rows one read returns; allowAggregations allows ...Aggregate fields, totalCount and Prefer: count=exact.

X-Excalibase-User-Id is a session variable taken from the verified token. Other claims of the token are available as X-Excalibase-<Claim>. Expressions use the Hasura grammar: _eq, _neq, _gt, _in, _like, _is_null, _and, _or, _not, and relationships.

Seeing what a role gets

The demo project grants anon read access to feedback posts and nothing on the kanban tables. The tables a role can read are the ones in its schema:

{
  __type(name: "Query") {
    fields { name }
  }
}

A table the role cannot read answers 404 over REST:

curl -s "$BASE/$PROJECT_ID/api/v1/kanban_boards" \
  -H "Authorization: Bearer $TOKEN"

A refused write answers 403 with a typed code; see Errors.

Realtime

A subscription is accepted only for a table the role can read, and each change is delivered only when its row passes the select filter. See Subscriptions.

Self-hosting

This section is for running the engine yourself. The permission model is the same. A standalone engine verifies bearer tokens against a key source you configure, and refuses unverified ones rather than treating them as anon:

app:
  security:
    jwt-enabled: true
    auth:
      jwks-url: https://auth.example.com/.well-known/jwks.json   # excalibase-auth or any OIDC provider
      require-aud: true                                          # aud must cover the project in the URL path

Any OIDC provider that publishes a JWKS endpoint works. See the engine's permissions reference for the full grammar.