Appearance
roles
4 endpoints.
GET /api/v1/roles
List Role App Access
200 — Successful Response
json
{
"properties": {
"roles": {
"items": {
"properties": {
"role": {
"type": "string",
"title": "Role"
},
"app_slugs": {
"items": {
"type": "string"
},
"type": "array",
"title": "App Slugs"
}
},
"type": "object",
"required": [
"role"
],
"title": "RoleAppAccess",
"description": "One role's fixed app allowlist, or None (omitted app_slugs) if unaffected —\nsee app.core.apps.role_allowed_apps for the exact semantics."
},
"type": "array",
"title": "Roles"
},
"apps": {
"items": {
"properties": {
"slug": {
"type": "string",
"title": "Slug"
},
"name": {
"type": "string",
"title": "Name"
},
"icon": {
"type": "string",
"title": "Icon"
},
"system": {
"type": "boolean",
"title": "System"
}
},
"type": "object",
"required": [
"slug",
"name",
"icon",
"system"
],
"title": "CatalogAppOut",
"description": "A full-catalog app entry, independent of any site's install state — the\nRoles page is platform-wide, so it must show every app, not just the ones\ninstalled on whichever site happens to be active."
},
"type": "array",
"title": "Apps"
},
"custom_roles": {
"items": {
"type": "string"
},
"type": "array",
"title": "Custom Roles"
},
"is_customer_portal_site": {
"type": "boolean",
"title": "Is Customer Portal Site",
"default": false
}
},
"type": "object",
"required": [
"roles",
"apps"
],
"title": "RoleAppAccessPage"
}POST /api/v1/roles
Create Role
Add a new custom role (a capped peer of "sales" — see app.core.apps.add_role). Returns the full page so the frontend can just re-render from the response.
Request body
json
{
"properties": {
"name": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"title": "Name"
}
},
"type": "object",
"required": [
"name"
],
"title": "RoleCreate"
}201 — Successful Response
json
{
"properties": {
"roles": {
"items": {
"properties": {
"role": {
"type": "string",
"title": "Role"
},
"app_slugs": {
"items": {
"type": "string"
},
"type": "array",
"title": "App Slugs"
}
},
"type": "object",
"required": [
"role"
],
"title": "RoleAppAccess",
"description": "One role's fixed app allowlist, or None (omitted app_slugs) if unaffected —\nsee app.core.apps.role_allowed_apps for the exact semantics."
},
"type": "array",
"title": "Roles"
},
"apps": {
"items": {
"properties": {
"slug": {
"type": "string",
"title": "Slug"
},
"name": {
"type": "string",
"title": "Name"
},
"icon": {
"type": "string",
"title": "Icon"
},
"system": {
"type": "boolean",
"title": "System"
}
},
"type": "object",
"required": [
"slug",
"name",
"icon",
"system"
],
"title": "CatalogAppOut",
"description": "A full-catalog app entry, independent of any site's install state — the\nRoles page is platform-wide, so it must show every app, not just the ones\ninstalled on whichever site happens to be active."
},
"type": "array",
"title": "Apps"
},
"custom_roles": {
"items": {
"type": "string"
},
"type": "array",
"title": "Custom Roles"
},
"is_customer_portal_site": {
"type": "boolean",
"title": "Is Customer Portal Site",
"default": false
}
},
"type": "object",
"required": [
"roles",
"apps"
],
"title": "RoleAppAccessPage"
}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}PUT /api/v1/roles/{role}
Update Role App Access
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
role | path | yes | string |
Request body
json
{
"properties": {
"app_slugs": {
"items": {
"type": "string"
},
"type": "array",
"title": "App Slugs"
}
},
"type": "object",
"title": "RoleAppAccessUpdate"
}200 — Successful Response
json
{
"properties": {
"role": {
"type": "string",
"title": "Role"
},
"app_slugs": {
"items": {
"type": "string"
},
"type": "array",
"title": "App Slugs"
}
},
"type": "object",
"required": [
"role"
],
"title": "RoleAppAccess",
"description": "One role's fixed app allowlist, or None (omitted app_slugs) if unaffected —\nsee app.core.apps.role_allowed_apps for the exact semantics."
}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}DELETE /api/v1/roles/{role}
Delete Role
Remove a custom role. Built-in roles (viewer/sales/debt_collector/admin/ owner) can't be deleted — only ones added via POST /roles.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
role | path | yes | string |
200 — Successful Response
json
{
"properties": {
"roles": {
"items": {
"properties": {
"role": {
"type": "string",
"title": "Role"
},
"app_slugs": {
"items": {
"type": "string"
},
"type": "array",
"title": "App Slugs"
}
},
"type": "object",
"required": [
"role"
],
"title": "RoleAppAccess",
"description": "One role's fixed app allowlist, or None (omitted app_slugs) if unaffected —\nsee app.core.apps.role_allowed_apps for the exact semantics."
},
"type": "array",
"title": "Roles"
},
"apps": {
"items": {
"properties": {
"slug": {
"type": "string",
"title": "Slug"
},
"name": {
"type": "string",
"title": "Name"
},
"icon": {
"type": "string",
"title": "Icon"
},
"system": {
"type": "boolean",
"title": "System"
}
},
"type": "object",
"required": [
"slug",
"name",
"icon",
"system"
],
"title": "CatalogAppOut",
"description": "A full-catalog app entry, independent of any site's install state — the\nRoles page is platform-wide, so it must show every app, not just the ones\ninstalled on whichever site happens to be active."
},
"type": "array",
"title": "Apps"
},
"custom_roles": {
"items": {
"type": "string"
},
"type": "array",
"title": "Custom Roles"
},
"is_customer_portal_site": {
"type": "boolean",
"title": "Is Customer Portal Site",
"default": false
}
},
"type": "object",
"required": [
"roles",
"apps"
],
"title": "RoleAppAccessPage"
}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}