curl --request POST \
--url 'https://management.scanova.io/multi-users/access-levels/' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "Regional Support",
"permissions": [23, 24, 31]
}'
{
"id": 42,
"name": "Regional Support",
"slug": null,
"permissions": [
{ "id": 23, "code": "QR_CODE_CAN_VIEW", "name": "Can view QR Code", "description": "Allows viewing QR code details.", "is_boolean": true },
{ "id": 24, "code": "ANALYTICS_CAN_VIEW", "name": "Can view Analytics", "description": "Allows viewing analytics.", "is_boolean": true },
{ "id": 31, "code": "LEAD_GENERATION_CAN_VIEW", "name": "Can view Lead Lists", "description": "Allows viewing lead lists.", "is_boolean": true }
],
"is_custom": true
}
Management API — Shared Users & Roles
Create a custom role
POST /multi-users/access-levels/
POST
/
multi-users
/
access-levels
/
curl --request POST \
--url 'https://management.scanova.io/multi-users/access-levels/' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "Regional Support",
"permissions": [23, 24, 31]
}'
{
"id": 42,
"name": "Regional Support",
"slug": null,
"permissions": [
{ "id": 23, "code": "QR_CODE_CAN_VIEW", "name": "Can view QR Code", "description": "Allows viewing QR code details.", "is_boolean": true },
{ "id": 24, "code": "ANALYTICS_CAN_VIEW", "name": "Can view Analytics", "description": "Allows viewing analytics.", "is_boolean": true },
{ "id": 31, "code": "LEAD_GENERATION_CAN_VIEW", "name": "Can view Lead Lists", "description": "Allows viewing lead lists.", "is_boolean": true }
],
"is_custom": true
}
Every shared user is assigned a role — Scanova’s dashboard calls these “access levels” internally, and the same term appears throughout this endpoint. Use this endpoint to look up available roles before inviting a teammate via
POST /multi-users/, or to create a custom role from your own systems.
This endpoint was not previously documented. It requires a Management API key with
MANAGEMENT_API (or MANAGEMENT_API_SANDBOX) quota — see the Management API overview. For what each role actually grants a teammate, see the human-facing Roles & permissions guide — this page only documents the wire format.Creating custom roles requires a dedicated quota on the account’s plan (the same gate that hides the dashboard’s Roles tab on unsupported plans — see Custom roles are plan-gated). A 403 here means the plan doesn’t include it.
curl --request POST \
--url 'https://management.scanova.io/multi-users/access-levels/' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"name": "Regional Support",
"permissions": [23, 24, 31]
}'
{
"id": 42,
"name": "Regional Support",
"slug": null,
"permissions": [
{ "id": 23, "code": "QR_CODE_CAN_VIEW", "name": "Can view QR Code", "description": "Allows viewing QR code details.", "is_boolean": true },
{ "id": 24, "code": "ANALYTICS_CAN_VIEW", "name": "Can view Analytics", "description": "Allows viewing analytics.", "is_boolean": true },
{ "id": 31, "code": "LEAD_GENERATION_CAN_VIEW", "name": "Can view Lead Lists", "description": "Allows viewing lead lists.", "is_boolean": true }
],
"is_custom": true
}
string
required
Role name. Must be unique among this account’s roles — a duplicate returns a 400 with
{"name": ["Can not create another user role with the same name."]}.array
required
Permission IDs to grant, from the
permissions[].id values in the list response above.There’s no bulk “list all available permissions independent of a role” endpoint on the Management API — to discover permission IDs, read them off an existing role’s
permissions array (every account has at least the 6 system roles to inspect).Related
- List roles — the other operation on this same endpoint.
- Invite a shared user — assign a role ID from this list when inviting or updating a teammate.
- Update a shared user — assign a role ID from this list when inviting or updating a teammate.
- Roles & permissions — the human-facing explanation of what each role grants, including the custom-roles plan gate.
- Shared users — the dashboard’s Users table where these roles are assigned via the UI.
Authorizations
Send your Management API key as the raw value of the Authorization header — no "Bearer " or "Token " prefix, and no other characters. Example: Authorization: 401f7ac837da42b97f613d789819ff93537bee6a. A header containing more than one space-separated part is rejected outright. Requests also require the request's Host header to be the management API host (e.g. management.scanova.io) — the same key sent to the regular API host will not authenticate.
Body
application/json
Response
201 - application/json
Custom role created. Requires the account's custom-roles plan quota.
Was this page helpful?
⌘I