Roles

Planned feature: The endpoints described on this page are part of the planned API design and are not yet implemented in the current codebase.

The planned Roles API will allow you to create and manage custom roles with fine-grained permissions. Roles will define what actions users can perform within an organization.

Authentication

All role endpoints require authentication using a JWT bearer token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Get roles

This endpoint returns roles available within the specified organization. System-defined roles (owner, admin, member, viewer) are included along with any custom roles.

GET /api/roles

Retrieves a list of roles. You can filter and sort the results using query parameters.

Query parameters

organizationId

string

required

Organization ID to retrieve roles from (UUID)

page

integer

default:"1"

The page number for pagination

limit

integer

default:"20"

Number of roles to return per page (maximum 100)

sort

string

default:"name"

Field to sort by. Options: name, createdAt, updatedAt

order

string

default:"asc"

Sort order. Options: asc, desc

type

string

Filter by role type. Options: system, custom

string

Search roles by name or description

Response

data

array

Array of role objects

Show Role object

string

required

Unique identifier for the role (UUID)

name

string

required

Role name (e.g., “admin”, “member”, “billing-manager”)

displayName

string

required

Human-readable role name

description

string

Description of the role’s purpose and permissions

type

string

required

Role type. Options: system (built-in, cannot be modified), custom (user-defined)

organizationId

string

required

Organization this role belongs to (UUID)

permissions

array

required

Array of permission strings granted to this role

Show Available permissions

organizations.read

string

View organization details

organizations.update

string

Update organization settings

organizations.delete

string

Delete the organization

users.read

string

View users in the organization

users.create

string

Create new users

users.update

string

Update user information

users.delete

string

Remove users from the organization

roles.read

string

View roles and permissions

roles.create

string

Create custom roles

roles.update

string

Modify role permissions

roles.delete

string

Delete custom roles

roles.assign

string

Assign roles to users

userCount

integer

Number of users assigned to this role

isDefault

boolean

required

Whether this is the default role for new organization members

metadata

object

Custom metadata key-value pairs

createdAt

string

required

ISO 8601 timestamp when the role was created

updatedAt

string

required

ISO 8601 timestamp when the role was last updated

pagination

object

Pagination metadata

Show Pagination object

Example request

curl -X GET "https://api.orgstack.io/api/roles?organizationId=550e8400-e29b-41d4-a716-446655440000&page=1&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Example response

200 - Success

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a5b-8c7d-9e0f1a2b3c4d",
      "name": "admin",
      "displayName": "Administrator",
      "description": "Full access to all organization resources and settings",
      "type": "system",
      "organizationId": "550e8400-e29b-41d4-a716-446655440000",
      "permissions": [
        "organizations.read",
        "organizations.update",
        "users.read",
        "users.create",
        "users.update",
        "users.delete",
        "roles.read",
        "roles.create",
        "roles.update",
        "roles.delete",
        "roles.assign"
      ],
      "userCount": 3,
      "isDefault": false,
      "metadata": {},
      "createdAt": "2024-01-15T08:30:00.000Z",
      "updatedAt": "2024-01-15T08:30:00.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-5b6c-9d8e-0f1a2b3c4d5e",
      "name": "member",
      "displayName": "Member",
      "description": "Standard member with read and write access to most resources",
      "type": "system",
      "organizationId": "550e8400-e29b-41d4-a716-446655440000",
      "permissions": [
        "organizations.read",
        "users.read",
        "roles.read"
      ],
      "userCount": 15,
      "isDefault": true,
      "metadata": {},
      "createdAt": "2024-01-15T08:30:00.000Z",
      "updatedAt": "2024-01-15T08:30:00.000Z"
    },
    {
      "id": "c3d4e5f6-a7b8-6c7d-0e9f-1a2b3c4d5e6f",
      "name": "billing-manager",
      "displayName": "Billing Manager",
      "description": "Manages billing, subscriptions, and payment methods",
      "type": "custom",
      "organizationId": "550e8400-e29b-41d4-a716-446655440000",
      "permissions": [
        "organizations.read",
        "billing.read",
        "billing.update",
        "subscriptions.read",
        "subscriptions.update",
        "invoices.read"
      ],
      "userCount": 2,
      "isDefault": false,
      "metadata": {
        "department": "Finance",
        "createdBy": "[email protected]"
      },
      "createdAt": "2024-03-10T14:20:00.000Z",
      "updatedAt": "2024-03-10T14:20:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 3,
    "totalPages": 1
  }
}

401 - Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication token"
  }
}

403 - Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to view roles in this organization"
  }
}

404 - Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Organization not found"
  }
}

Create role

Creating custom roles requires roles.create permission. System roles (owner, admin, member, viewer) cannot be created or modified. Only custom roles can be created and edited.

POST /api/roles

Creates a new custom role with specified permissions. Role names must be unique within an organization.

Request body

name

string

required

Role name (3-50 characters, lowercase letters, numbers, and hyphens only)

displayName

string

required

Human-readable role name (2-100 characters)

description

string

Description of the role’s purpose (up to 500 characters)

organizationId

string

required

Organization ID to create the role in (UUID)

permissions

array

required

Array of permission strings to grant to this role. Must include at least one permission.

Show Available permissions

organizations.read - View organization details
organizations.update - Update organization settings
organizations.delete - Delete the organization
users.read - View users
users.create - Create users
users.update - Update users
users.delete - Delete users
roles.read - View roles
roles.create - Create roles
roles.update - Update roles
roles.delete - Delete roles
roles.assign - Assign roles to users
billing.read - View billing information
billing.update - Update billing settings
subscriptions.read - View subscriptions
subscriptions.update - Manage subscriptions
invoices.read - View invoices
api-keys.read - View API keys
api-keys.create - Create API keys
api-keys.delete - Delete API keys

isDefault

boolean

default:"false"

Whether this should be the default role for new members. Only one role can be default per organization.

metadata

object

Custom metadata as key-value pairs (optional)

Response

Returns the created role object with all fields populated, including generated id, createdAt, and updatedAt timestamps.

string

required

Unique identifier for the role (UUID)

name

string

required

Role name

displayName

string

required

Human-readable role name

description

string

Role description

type

string

required

Role type (always custom for created roles)

organizationId

string

required

Organization ID

permissions

array

required

Array of granted permissions

userCount

integer

Number of users with this role (0 for new roles)

isDefault

boolean

required

Whether this is the default role

metadata

object

Custom metadata

createdAt

string

required

ISO 8601 timestamp when created

updatedAt

string

required

ISO 8601 timestamp when last updated

Example request

curl -X POST "https://api.orgstack.io/api/roles" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "content-editor",
    "displayName": "Content Editor",
    "description": "Can create and edit content but cannot publish or delete",
    "organizationId": "550e8400-e29b-41d4-a716-446655440000",
    "permissions": [
      "organizations.read",
      "content.read",
      "content.create",
      "content.update",
      "media.read",
      "media.upload"
    ],
    "isDefault": false,
    "metadata": {
      "department": "Marketing",
      "accessLevel": "standard"
    }
  }'

Example response

201 - Created

{
  "id": "d4e5f6a7-b8c9-7d8e-1f0a-2b3c4d5e6f7a",
  "name": "content-editor",
  "displayName": "Content Editor",
  "description": "Can create and edit content but cannot publish or delete",
  "type": "custom",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "permissions": [
    "organizations.read",
    "content.read",
    "content.create",
    "content.update",
    "media.read",
    "media.upload"
  ],
  "userCount": 0,
  "isDefault": false,
  "metadata": {
    "department": "Marketing",
    "accessLevel": "standard"
  },
  "createdAt": "2026-03-01T10:30:00.000Z",
  "updatedAt": "2026-03-01T10:30:00.000Z"
}

400 - Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "permissions",
        "message": "At least one permission is required"
      },
      {
        "field": "name",
        "message": "Role name must contain only lowercase letters, numbers, and hyphens"
      }
    ]
  }
}

401 - Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication token"
  }
}

403 - Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to create roles in this organization"
  }
}

404 - Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Organization not found"
  }
}

409 - Conflict

{
  "error": {
    "code": "CONFLICT",
    "message": "A role with this name already exists in the organization"
  }
}

Permission hierarchy

Permissions follow a hierarchical structure. Some permissions implicitly grant related permissions:

organizations.delete includes organizations.update and organizations.read
users.delete includes users.update and users.read
roles.assign includes roles.read

When designing custom roles, consider the minimum permissions needed for the role’s purpose.

Error codes

The Roles API may return the following error codes:

Code	Description
`UNAUTHORIZED`	Missing or invalid authentication token
`FORBIDDEN`	Insufficient permissions to perform the action
`VALIDATION_ERROR`	Request body validation failed
`CONFLICT`	Resource conflict (e.g., duplicate role name)
`NOT_FOUND`	Role or organization not found
`RATE_LIMIT_EXCEEDED`	Too many requests, please retry later
`INTERNAL_ERROR`	Unexpected server error

Overview

Endpoints

Authentication

Get roles

Query parameters

Response

Example request

Example response

Create role

Request body

Response

Example request

Example response

Permission hierarchy

Error codes

Build docs developers (and LLMs) love

Overview

Endpoints

​Authentication

​Get roles

​Query parameters

​Response

​Example request

​Example response

​Create role

​Request body

​Response

​Example request

​Example response

​Permission hierarchy

​Error codes

Build docs developers (and LLMs) love

Authentication

Get roles

Query parameters

Response

Example request

Example response

Create role

Request body

Response

Example request

Example response

Permission hierarchy

Error codes