👥 User Management

Securial provides a built-in system for managing users and their roles, primarily intended for use by administrators (e.g. users with the superusers role). These features are exposed via JSON API endpoints.

---

🧭 Accessing Admin Endpoints

Admin-level user management endpoints are scoped under the /securial/superusers/ path by default.

You must authenticate with a valid access token belonging to a user who has the superusers role.

---

📋 Users Endpoints

HTTP Verb	Path	Description
GET	/securial/superusers/users	List all users
POST	/securial/superusers/users	Create a new user
PUT/PATCH	/securial/superusers/users/:id	Update a user
DELETE	/securial/superusers/users/:id	Delete a user

Example: Create User

curl -X POST http://localhost:3000/securial/superusers/users \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "username": "exampleuser",
    "password": "strongpassword"
  }'

---

🎭 Roles Endpoints

HTTP Verb	Path	Description
GET	/securial/superusers/roles	List roles
POST	/securial/superusers/roles	Create a new role
PUT/PATCH	/securial/superusers/roles/:id	Update a role
DELETE	/securial/superusers/roles/:id	Delete a role

---

🎯 Role Assignment

HTTP Verb	Path	Description
POST	/securial/superusers/role_assignments/assign	Assign a role to a user
DELETE	/securial/superusers/role_assignments/revoke	Revoke a user's role

Example: Assign Role

curl -X POST http://localhost:3000/securial/superusers/role_assignments/assign \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 42,
    "role_id": 1
  }'

Example: Revoke Role

curl -X DELETE http://localhost:3000/securial/superusers/role_assignments/revoke \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 42,
    "role_id": 1
  }'

---

🚫 Error Responses

Securial returns standard HTTP status codes with JSON bodies. Here are common examples:

Status	Reason	Example Message
401	Unauthorized	{ "error": "Unauthorized" }
403	Forbidden	{ "error": "Forbidden" }
404	Not Found	{ "error": "User not found" }
422	Validation Failed	{ "errors": { "email_address": ["is invalid"] } }

---

📏 Validations

When creating or updating users and roles, Securial enforces the following validations:

User

• email_address must be:
  • present
  • unique
  • valid email format
• username must be:
  • present
  • unique
  • 3–30 characters
• password must be:
  • present on create
  • at least 8 characters (default)
  • strong (if enabled by your config)

Role

• name must be:
  • present
  • unique
  • lowercase and hyphenated (e.g. admin-user)

---

🔐 Requirements

• All endpoints require a valid Bearer token.
• Only users with appropriate roles (e.g. superusers) may access user management routes.

---

🧩 Want to Customize?

Check the Configuration page to override views or change authorization behavior.