RBAC & multi-tenancy

RestWard is a multi-tenant platform: every organization (tenant) owns its own APIs, database connections, API keys, and user memberships. Access to every resource is scoped to the organization in the caller's JWT org_id claim, and every action is authorized against the caller's role.

Organizations and the org-scoping model

Every authenticated request to the RestWard control plane carries a JWT access token that contains an org_id claim identifying the organization context. Every request targeting a specific organization must match the caller's org_id claim. SystemAdmin users are the only exception: they transcend tenant boundaries and can access any organization.

When you sign in or switch organizations, RestWard issues a JWT with the chosen organization's ID in the org_id claim. Every subsequent request automatically operates within that organization's scope. You cannot access another organization's resources unless you switch to it or are a SystemAdmin.

Dashboard roles vs data-plane roles

RestWard has two distinct role systems:

Dashboard roles:

• SystemAdmin — Platform-level administrator with access to all organizations and platform settings
• Administrator — Full access to organization settings, member management, and all APIs
• Contributor — Can view and work with APIs, but cannot manage organization settings or members
• Auditor — Read-only access to organization data and audit logs
• Reader — Read-only access to organization APIs

Auditor and Reader are read-only in the dashboard: they can view everything but cannot change anything. Creating, changing, or deleting APIs, connections, endpoints, documentation settings, roles, and API keys is refused with "403 Forbidden".

Data-plane roles for your generated APIs:

• Admin — Full access: can read, create, update, patch, and delete
• ReadWrite — Can read, create, update, and patch; cannot delete
• ReadOnly — Read-only access: can only read (GET requests)

Dashboard roles control who can manage your RestWard organization and its APIs. Data-plane roles control what API consumers (via API keys, JWT, or mTLS) can do to your generated APIs. They are independent.

Custom roles for members (Professional and Enterprise)

Custom roles let an Administrator give a member exactly the dashboard permissions they need, instead of one of the four built-in roles. They are available on the Professional and Enterprise plans and are off by default.

What a custom role grants. A custom role lists, for each resource kind, which of three actions it allows: read, write (create and update) and delete. The resource kinds are fixed: apis, connections, endpoints, keys, members, roles, billing, settings, documentation, audit_logs and usage. A role grants an action on a whole resource kind in the organization, not on one individual API or connection.

A custom role replaces the built-in role. A member who is assigned a custom role gets only what that role grants. Their built-in role (kept for display) no longer applies, in either direction: an Administrator under a role that lacks members: write cannot manage members, and a Reader under a role with apis: write can edit APIs. Members without a custom role are unchanged. Anything the role does not mention is refused.

Turning it on. Open Access Control (RBAC), where an Administrator sees a banner explaining that custom roles are stored but not enforced. Choosing Enable custom roles activates them for the organization. Enabling changes nobody's access by itself: members keep their built-in roles until an Administrator assigns a custom role. Switching the setting off again returns every member to their built-in role; assignments are kept but have no effect.

Who can manage them. Only Administrators create, edit, delete and assign custom roles, and only up to their own permissions: nobody can grant an action they cannot perform themselves. This also holds for an Administrator who is themselves under a custom role. Assign a role to a member on the Users page (Custom role). Granting a member a built-in role afterwards ends their custom role.

The last administrator. An organization must always keep at least one active Administrator who has no custom role. A member under a custom role does not count as an Administrator for this rule, so assigning a custom role to the last such Administrator (yourself included) is refused.

Audit. Creating, renaming and deleting a role, every change to its permissions, turning the setting on or off, and every assignment are recorded in the role-change audit trail and in the audit log.

Custom data-plane roles (Professional and Enterprise)

A DataPlane role belongs to one API in one organization. It grants exact schema.table permissions for list, get, create, update, patch and delete separately. Missing grants deny access. There are no wildcard, row or column filters. A dashboard role cannot be assigned to a key, and a data-plane role cannot be assigned to a member.

On Access Control, create a data-plane role, choose its API, and edit the table × operation matrix. On API Keys or the API detail page, an Administrator can assign it to a key. The nullable customRoleId replaces the key's built-in ApiKeyRole, rather than adding to it: an Admin key with a list-only custom role cannot write; a ReadOnly key with a create grant can create. Clearing the assignment restores the enum. Rotation preserves the assignment. Keys without an assignment behave as before.

The organization enable switch controls both kinds of custom roles. While it is off, keys and JWT/mTLS callers retain their existing enum scopes; stored custom assignments and mappings have no effect. Existing grants remain enforced after a plan downgrade while the switch stays on; creating, widening or assigning custom roles requires the plan entitlement. Remove assignments or turn the switch off explicitly when returning to built-in roles.

JWT: keep normal signature, issuer, audience and lifetime validation. Configure a customRoleMappings object in the JWT method settings, mapping values of the dedicated restward_role claim to data-plane role IDs:

{
  "issuer": "https://identity.example.com",
  "audience": "orders-api",
  "jwksUri": "https://identity.example.com/.well-known/jwks.json",
  "customRoleMappings": {
    "orders-reader": "00000000-0000-0000-0000-000000000001",
    "orders-writer": "00000000-0000-0000-0000-000000000002"
  }
}

Repeated restward_role claims union the matching custom roles for the current API only. They never union the built-in scope. With mappings configured, a missing or unmatched dedicated claim denies access. An empty configured mapping object denies all JWT callers. With no custom mapping configured, the dedicated claim has no effect on legacy enum scopes. The existing roleClaim and defaultScope settings continue to control enum scopes when no custom mapping is configured. Role names and dashboard-role claims are never interpreted as data-plane role IDs. To clear existing JWT mappings, send customRoleMappings: null. Omitting either custom mapping property when saving an existing method preserves it, so editing ordinary JWT/certificate settings cannot accidentally remove a restriction.

mTLS: certificates carry no custom claims. After certificate acceptance using the existing CA/fingerprint/subject checks, customRoleIds in the mTLS method settings selects the roles for accepted clients:

{
  "allowedFingerprints": ["<accepted SHA-256 certificate fingerprint>"],
  "customRoleIds": ["00000000-0000-0000-0000-000000000001"]
}

Multiple IDs union custom grants for the current API. An empty configured list denies access. Set customRoleIds to null to return to defaultScope. JWT/mTLS method settings are organization-wide; mappings can reference roles from its APIs, but each runtime uses only roles bound to its own API.

Only current Administrators with the required effective management permissions can manage or assign data-plane roles and change their mappings. Adding grants or assignments requires effective keys: write authority; this is the same ceiling used to mint data-plane credentials. An Administrator restricted by a dashboard role can narrow existing grants but cannot add access beyond that authority. Changes are audited. Deleting a role assigned to a key (including a revoked key) or referenced by JWT/mTLS settings is refused until the assignment is removed.

Permissions and assignments reload with the existing 30-second policy refresh (EndpointConfig:RefreshSeconds). Requests use the in-memory snapshot and check access before cached responses. A failed refresh retains the last good grants; when that snapshot exceeds the existing staleness limit (default five minutes), authenticated traffic fails closed with 503, as for stale keys. Public endpoints remain public. Runtime OpenAPI paths and security schemes are unchanged; a custom grant never enables an endpoint disabled by configuration or exposes an excluded table.

SystemAdmin vs organization roles

SystemAdmin is a platform-level role that:

• Bypasses all organization scoping checks
• Can access any organization's resources
• Can manage platform-wide settings
• Can provision and manage tenant organizations

Organization roles (Administrator, Contributor, Auditor, Reader) apply only within a single organization:

• They are scoped by the org_id claim in the JWT
• They cannot access resources in other organizations
• They have no platform-level privileges

For customers: your organization will have users with Administrator, Contributor, Auditor, or Reader roles. SystemAdmin is reserved for platform operators and is not available to customers.

Designing least-privilege access for a read-only analytics consumer

There are two common scenarios: a person who needs dashboard access, or a service that needs API access.

For a person: assign the Reader dashboard role

The built-in Reader role provides read-only access to your organization's APIs and data:

1. Navigate to Users in the dashboard sidebar
2. Find the user in the list
3. Click the role dropdown and select Reader
4. Click Save

The user can now view APIs, connections, and metrics but cannot make any changes. Their role applies immediately.

For a service: create an API key with ReadOnly data-plane role

If the analytics consumer is a service or automated process:

1. Navigate to API Keys in the dashboard
2. Click Create API Key
3. Select the API the service needs to access
4. Set the role to ReadOnly
5. Optionally set an IP allowlist to restrict where the key can be used
6. Copy the generated API key

The service can now make authenticated requests to your generated APIs with read-only access. The key can read data but cannot create, update, patch, or delete.

Who can manage API keys: Creating, rotating, revoking, or changing API keys requires the Contributor role or above. Auditor and Reader are read-only: they can list and view keys but every change is refused with 403 Forbidden. Additionally, only Administrators can create or manage keys with the Admin data-plane role, and only Administrators can permanently delete a key.

Inviting members

You can invite members to your organization in two ways: direct invitation or via verified domains.

Direct invitation

Direct invitations let you assign a role immediately and skip the approval process:

1. Click Invitations in the sidebar
2. Click Invite Member
3. Enter the member's email address
4. Select their role (defaults to Reader)
5. Click Send Invitation

An invitation link is displayed in a success banner. Copy and share this link with the member. They can click the link to accept the invitation and join your organization with the assigned role.

Pending invitations appear in the Invitations table. You can copy the link to resend an invitation or revoke it before they accept.

Via verified domains

If your organization has verified domains configured, users who sign up with an email matching one of those domains automatically join your organization as a pending member. You must approve them before they can access your organization.

1. The user signs up with an email matching your verified domain
2. They appear in the Organization Users page with Pending status
3. Find the member in the list and click Approve

The user receives the Reader role by default and can now sign in and access your organization.

Note: Users who don't match a verified domain create their own organization instead.

The approval flow

When a user joins via a verified domain:

1. Pending state: The user appears in your Organization Users list with "Pending" status
2. Approval: An Administrator clicks Approve to activate their membership
3. Default role: The user receives the Reader role
4. Activation: The user can now sign in and access your organization

Only users with the Administrator role can approve pending members.

Offboarding members

When a member leaves your organization or no longer needs access, you have several options. Changing a member's role or status immediately invalidates their existing access tokens: any subsequent request fails with a 401 "stale_session" error, and they must refresh their session to get the reduced scope.

Deactivate a member

Deactivating a member removes their access without deleting their record:

1. Find the member in the Organization Users list
2. Click Deactivate
3. Confirm the action

What happens when a member is deactivated:

• They cannot sign in to your organization
• Their membership record is preserved (you can reactivate them later)
• Their existing access tokens are immediately invalidated
• Their API keys continue to work (they belong to the organization, not the individual)

Remove a member

To permanently remove a member from your organization:

1. Find the member in the Organization Users list
2. Click Delete
3. Confirm the action

What happens when a member is deleted:

• Their membership record is removed from your organization
• Their user account is NOT deleted (they can still sign in to RestWard and access other organizations)
• Their existing access tokens are immediately invalidated
• Their API keys continue to work (keys belong to the organization, not the individual)

Important: The Deactivate and Delete buttons are disabled if the member is your organization's last active Administrator. You must promote another Administrator first. You also cannot deactivate or delete yourself.

Revoke API keys

API keys belong to the organization and API, not to individual members. When a member leaves, review the API keys they had access to and revoke any that should no longer be active:

1. Navigate to API Keys in the dashboard
2. Review the list of keys for each API
3. Click Revoke for any key that should be disabled

What happens:

• The API key is immediately invalidated
• Any requests using that key receive a 401 Unauthorized response
• The key cannot be used again

Best practice: When offboarding a member, deactivate or delete them AND review and revoke any API keys that should no longer be active.

Cross-links to in-app help

The following in-app help pages cover related topics:

• Members & invitations — Detailed UI workflows for inviting, approving, deactivating, and removing members
• Tenants — Platform-level tenant management (SystemAdmin only)
• Single sign-on — Configuring SSO for your organization
• SCIM provisioning — Automated user provisioning from your identity provider
• Passkeys & security — Passkey authentication and security settings
• API keys & tenant API auth — Creating and managing API keys for your generated APIs
• Authentication methods — Choosing between API key, JWT, and mTLS for your generated APIs

See also

• Getting started — First steps with RestWard
• Dashboard & search — Navigating the RestWard dashboard
• Building & publishing APIs — Creating and configuring your REST APIs