Roles & permissions

#Roles & permissions

sdk.roles manages the role catalogue and each role's permission rows. A permission row grants an action on a resource (e.g. collections/products, or *), optionally narrowed by a row filter and by column lists.

Valid actions are read, create, update, delete, manage, execute, send, transfer, view_deleted, hard_delete, read_self and install (the last on system/blueprints only: opening and settling a blueprint install run). The gateway validates against exactly that list and answers Unknown action "<x>" for anything else, so a typo is a 400 rather than a rule that silently never matches.

#Role CRUD

const roles = await sdk.roles.list();

const { id } = await sdk.roles.create({
	name: 'moderator',
	description: 'Can review and edit community posts'
});

await sdk.roles.update(id, { description: 'Community moderation' });
await sdk.roles.remove(id);

#Permission rows

const rows = await sdk.roles.getPermissions(id);

await sdk.roles.setPermissions(id, [
	{
		resource: 'collections/posts',
		action: 'read'
	},
	{
		resource: 'collections/posts',
		action: 'update',
		// Row scope: only rows the caller ADDED. Server-resolved variables like
		// $CURRENT_USER work here exactly as in list filters.
		//
		// Note this is not the same as the Access screen's "only their own",
		// which since ownership became transferable means "transferred to me, or
		// made by me and never transferred". Use created_by when you mean
		// authorship; see /docs/permissions/ownership.
		item_filter: { created_by: { _eq: '$CURRENT_USER' } },
		// Field visibility: omit to allow all columns
		fields: ['title', 'body', 'status']
	}
]);

#Notes

• super_admin bypasses permission checks by design and cannot be locked out.
• API keys are additionally narrowed by their own scopes — the effective grant is role ∩ scopes (see API keys).
• Permission changes invalidate the gateway's policy cache immediately.

#What you learned

• sdk.roles covers role CRUD plus getPermissions/setPermissions
• Permission rows = resource + action, plus optional item_filter (which rows), fields (which columns may be read), ui_fields (which the dashboard shows), write_fields (which may be set), immutable_fields (which freeze after create), validation and presets — and a gateway-stamped source saying which writer produced the row
• Row filters reuse the collection filter grammar, including server variables