Skip to content

Create Role

Create a new role within a project and assign permission IDs to it.

Endpoint

/api/v1/projects/{project_id}/roles

Method

POST

Path Parameters

ParameterTypeRequiredDescription
project_idstringYesUnique ID of the project

Headers

HeaderRequiredDescription
Content-TypeYesapplication/json
AuthorizationYesBearer access token: Bearer <access_token>

Request Body

FieldTypeRequiredDescription
codestringYesRole code (alphanumeric, dash, underscore, max 50 chars)
namestringYesRole name (max 50 chars)
descriptionstringNoDescription (max 200 chars)
permission_idsarray of stringsNoList of permission IDs to assign to role

Required Permission

roles:create

Examples

curl --request POST \
  --url https://auth.roled.id/api/v1/projects/2JUSLUee46xG6iEwG8JwPc/roles \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Store Manager",
    "code": "store-manager",
    "description": "Manages store operations including products, orders, and staff",
    "permission_ids": [
      "2JUUyotLUqz5eqsuYXXDet",
      "2JUUyotLUr7SuBqkzjRbTc",
      "2JUUyotLUrApxL7zcx7Xoy",
      "2JUUyotLUrDfBK9iwe25jj",
      "2JRjbZKS7f4oRkDaAD4gAF",
      "2JRjbZKS7fJAfNjgShH3TE",
      "2JRjbZKS7h72qSpPAJBuSj"
    ]
  }'

Error Codes

CodeHTTP StatusDescription
invalid_params400Missing or invalid request params, headers, or body
invalid_authorization_token401Missing or invalid authorization token
insufficient_permission403Insufficient permission
project_not_found404Project not found
some_permissions_not_found404One or more specified permission IDs not found
role_code_already_used409Role with the same code already exists
system_error500Internal server error