Multi-Role Feature

Add custom role

Add a custom role to a project with specific permissions and signup endpoint. Optional **`featurePermissions`** must align with app JWT gates — see `components/schemas/AppRoleFeaturePermissions` and `services/appRoleFeatureMap.js`. Accepts: OrgBearerAuth (for admin users), ProjectBearerAuth (JWT for authenticated users), or ApiKeyAuth (X-API-Key for programmatic access). Both ProjectBearerAuth and ApiKeyAuth are fully implemented.

AuthBearer (JWT)
GroupMulti-Role Feature
Rate limitSee Rate Limits
POST/api/projects/{projectId}/multi-role/roles

SDK setup

Create a client and set credentials (JWT and/or API key) before calling the API. Match the authentication type shown above.

import { Configuration, MultiRoleFeatureApi } from 'mudbase-sdk';

const configuration = new Configuration({
  basePath: 'https://cloud.mudbase.dev',
  accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfbW9yZ2FuX2RlIiwiZW1haWwiOiJtb3JnYW4uY2hlbkBub3J0aHdpbmQuZGV2IiwiZXhwIjoxODI1MTI5NjAwfQ.doc_preview_sig',
});

const multirolefeature = new MultiRoleFeatureApi(configuration);
import { Configuration, MultiRoleFeatureApi } from 'mudbase-sdk';

const configuration = new Configuration({
  basePath: 'https://cloud.mudbase.dev',
  accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfbW9yZ2FuX2RlIiwiZW1haWwiOiJtb3JnYW4uY2hlbkBub3J0aHdpbmQuZGV2IiwiZXhwIjoxODI1MTI5NjAwfQ.doc_preview_sig',
});

const multirolefeature = new MultiRoleFeatureApi(configuration);

Example request

Call this endpoint using the client from SDK setup. Use View HTTP for a raw cURL example.

const { data: result } = await multirolefeature.addCustomRole(
  "proj_WH6eS54ADsVY",
  {
    slug: "normal-depot-s88r",
    name: "Micaela McClure",
    description: "Our sweet-inspired Bacon brings a taste of luxury to your stunning lifestyle",
    signupEndpoint: "circuit calculate",
    requiresApproval: true,
    requiresPayment: false,
    requiresKYC: false,
    defaultPermissions: "capacitor index",
    collectionPermissions: "bus back up",
    metadata: "bus connect",
    featurePermissions: "port override"
  }
);
const { data: result } = await multirolefeature.addCustomRole(
  "proj_WH6eS54ADsVY",
  {
    slug: "normal-depot-s88r",
    name: "Micaela McClure",
    description: "Our sweet-inspired Bacon brings a taste of luxury to your stunning lifestyle",
    signupEndpoint: "circuit calculate",
    requiresApproval: true,
    requiresPayment: false,
    requiresKYC: false,
    defaultPermissions: "capacitor index",
    collectionPermissions: "bus back up",
    metadata: "bus connect",
    featurePermissions: "port override"
  }
);

Playground

live

Test this endpoint with your own credentials. Your requests will be sent to the live API.

Use the auth endpoints to obtain a JWT.

No Request Yet

Send a request to see the full inspector

Authentication

Requires JWT
Note
Include your JWT in the Authorization: Bearer YOUR_TOKEN header (user-facing apps, RBAC). View authentication guide →

Path Parameters

NameTypeRequiredDescription
projectIdstringYes—

Request Body

json
{
  "slug": "seller",
  "name": "Seller",
  "description": "Seller role with CRUD on seller-owned collections",
  "signupEndpoint": "seller",
  "requiresApproval": false,
  "requiresPayment": false,
  "requiresKYC": false,
  "defaultPermissions": [
    {
      "resource": "panel calculate",
      "actions": [
        "alarm transmit"
      ]
    }
  ],
  "collectionPermissions": {},
  "metadata": {},
  "featurePermissions": {
    "messaging": {
      "email": true,
      "sms": true,
      "push": false,
      "history": true,
      "stats": true
    },
    "integration": {
      "read": true,
      "execute": true
    },
    "storage": {
      "read": true,
      "upload": true
    }
  }
}
{
  "slug": "seller",
  "name": "Seller",
  "description": "Seller role with CRUD on seller-owned collections",
  "signupEndpoint": "seller",
  "requiresApproval": false,
  "requiresPayment": false,
  "requiresKYC": false,
  "defaultPermissions": [
    {
      "resource": "panel calculate",
      "actions": [
        "alarm transmit"
      ]
    }
  ],
  "collectionPermissions": {},
  "metadata": {},
  "featurePermissions": {
    "messaging": {
      "email": true,
      "sms": true,
      "push": false,
      "history": true,
      "stats": true
    },
    "integration": {
      "read": true,
      "execute": true
    },
    "storage": {
      "read": true,
      "upload": true
    }
  }
}

Responses

201Custom role added
json
{
  "success": true,
  "message": "Custom role added",
  "data": {
    "slug": "seller",
    "name": "Seller",
    "description": "Seller role with CRUD on seller-owned collections",
    "isEnabled": true,
    "isCustom": true,
    "signupEndpoint": "seller",
    "requiresApproval": false,
    "requiresPayment": false,
    "requiresKYC": false,
    "defaultPermissions": [
      {
        "resource": "project",
        "actions": [
          "read"
        ]
      },
      {
        "resource": "data",
        "actions": [
          "read",
          "create"
        ]
      }
    ],
    "collectionPermissions": [
      {
        "collectionSlug": "listings",
        "actions": [
          "create",
          "read",
          "update",
          "delete"
        ]
      },
      {
        "collectionSlug": "orders",
        "actions": [
          "create",
          "read"
        ],
        "conditions": {
          "status": "active"
        }
      }
    ],
    "metadata": {},
    "featurePermissions": {
      "messaging": {
        "email": true,
        "sms": true,
        "push": true,
        "history": true,
        "stats": true
      },
      "integration": {
        "read": true,
        "create": true,
        "update": true,
        "delete": false,
        "execute": true,
        "test": true,
        "export": true,
        "read_usage": true
      },
      "functions": {
        "create": true,
        "read": true,
        "update": true,
        "delete": false,
        "execute": true,
        "simulate": true
      },
      "data": {
        "create": true,
        "read": true,
        "update": true,
        "delete": false
      },
      "search": {
        "query": true,
        "suggestions": true,
        "read_analytics": true
      },
      "usage": {
        "read": true
      },
      "storage": {
        "read": true,
        "create": true,
        "update": true,
        "delete": false,
        "upload": true
      },
      "chat": {
        "read": true,
        "create": true,
        "update": true,
        "delete": false
      },
      "realtime": {
        "read_analytics": true,
        "read_active_users": true,
        "presence": true,
        "read_throughput": true,
        "read_history": true
      },
      "roleElevation": {
        "request": true,
        "status": true,
        "documents": true
      },
      "webhooks": {
        "config_read": true,
        "config_update": true,
        "test_transformation": true
      }
    }
  }
}
{
  "success": true,
  "message": "Custom role added",
  "data": {
    "slug": "seller",
    "name": "Seller",
    "description": "Seller role with CRUD on seller-owned collections",
    "isEnabled": true,
    "isCustom": true,
    "signupEndpoint": "seller",
    "requiresApproval": false,
    "requiresPayment": false,
    "requiresKYC": false,
    "defaultPermissions": [
      {
        "resource": "project",
        "actions": [
          "read"
        ]
      },
      {
        "resource": "data",
        "actions": [
          "read",
          "create"
        ]
      }
    ],
    "collectionPermissions": [
      {
        "collectionSlug": "listings",
        "actions": [
          "create",
          "read",
          "update",
          "delete"
        ]
      },
      {
        "collectionSlug": "orders",
        "actions": [
          "create",
          "read"
        ],
        "conditions": {
          "status": "active"
        }
      }
    ],
    "metadata": {},
    "featurePermissions": {
      "messaging": {
        "email": true,
        "sms": true,
        "push": true,
        "history": true,
        "stats": true
      },
      "integration": {
        "read": true,
        "create": true,
        "update": true,
        "delete": false,
        "execute": true,
        "test": true,
        "export": true,
        "read_usage": true
      },
      "functions": {
        "create": true,
        "read": true,
        "update": true,
        "delete": false,
        "execute": true,
        "simulate": true
      },
      "data": {
        "create": true,
        "read": true,
        "update": true,
        "delete": false
      },
      "search": {
        "query": true,
        "suggestions": true,
        "read_analytics": true
      },
      "usage": {
        "read": true
      },
      "storage": {
        "read": true,
        "create": true,
        "update": true,
        "delete": false,
        "upload": true
      },
      "chat": {
        "read": true,
        "create": true,
        "update": true,
        "delete": false
      },
      "realtime": {
        "read_analytics": true,
        "read_active_users": true,
        "presence": true,
        "read_throughput": true,
        "read_history": true
      },
      "roleElevation": {
        "request": true,
        "status": true,
        "documents": true
      },
      "webhooks": {
        "config_read": true,
        "config_update": true,
        "test_transformation": true
      }
    }
  }
}
Run in PostmanDownload OpenAPI

Next

NEXT →API Reference OverviewBase URL, rate limits, pagination, and the full endpoint index.NEXT →AuthenticationAPI keys, Bearer tokens, and user sessions.NEXT →API PlaygroundSearch any endpoint and send a live request.
Edit this page on GitHub