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
| Role | Who |
|---|---|
anon | A request with no token, or a token from a publishable key. |
user | A signed-in end user: the default role Auth gives accounts. |
| any other name | A custom role carried by the token's role claim, for example editor. |
service | A 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" }
}
}
filteris ANDed into every read of the table, including nested reads, cursors and counts.columnslists what the role may read or write.setfills a column from the caller (here the signed-in user's id) and the client cannot send it.checkmust hold for a written row, or the write is refused with403 permission_check_failed.limitcaps the rows one read returns;allowAggregationsallows...Aggregatefields,totalCountandPrefer: 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.