Usage - AlyBadawy/Securial GitHub Wiki

😎 Usage

This page describes how to use Securial once it’s installed in your host application.

🧱 What Securial Provides

Securial is a Rails engine that adds a secure, role-based authentication and account system to your API-only application. It provides:

  • A set of JSON API endpoints for sessions, user management, password reset, and role assignments.
  • JWT-based authentication for stateless client interactions.
  • Admin-level routes under a configurable namespace.
    assuming /superusers in this wiki, but this can be changed in Configuration.
  • A mountable engine route for easy integration.

πŸ”— Mounting the Engine

In your config/routes.rb, mount the engine:

mount Securial::Engine => "/securial"

This exposes all Securial functionality under the /securial namespace.

πŸ“‘ Available Endpoints

πŸ”„ Sessions

HTTP Verb Path Description
GET /securial/sessions List all active sessions for current user
GET /securial/sessions/current Show current session
GET /securial/sessions/id/:id Show specific session by ID
POST /securial/sessions/login Log in with email and password
DELETE /securial/sessions/logout Log out from current session
PUT /securial/sessions/refresh Refresh session using access token
DELETE /securial/sessions/revoke Revoke current session (logout)
DELETE /securial/sessions/id/:id/revoke Revoke specific session by ID
DELETE /securial/sessions/revoke_all Revoke all sessions

πŸ‘€ Accounts

HTTP Verb Path Description
GET /securial/accounts/me Get current user account
GET /securial/accounts/account/:username Get user account by username
POST /securial/accounts/register Register a new user
PUT /securial/accounts/update Update current user profile
DELETE /securial/accounts/delete_account Delete current user account

πŸ” Password Reset

HTTP Verb Path Description
POST /securial/password/forgot Request password reset email
PUT /securial/password/reset Reset password

πŸ›  Admin (Superusers)

HTTP Verb Path Description
GET /securial/superusers/users List all users
POST /securial/superusers/users Create a user
PUT/PATCH /securial/superusers/users/:id Update a user by ID
DELETE /securial/superusers/users/:id Delete a user by ID
GET /securial/superusers/roles List all roles
POST /securial/superusers/roles Create a role
PUT/PATCH /securial/superusers/roles/:id Update a role by ID
DELETE /securial/superusers/roles/:id Delete a role by ID
POST /securial/superusers/role_assignments/assign Assign a role to a user
DELETE /securial/superusers/role_assignments/revoke Revoke a role from a user

πŸ“Š Status Endpoint

HTTP Verb Path Description
GET /securial/status Health check/status ping

πŸ”‘ Authentication Headers

All authenticated endpoints require a Bearer token:

Authorization: Bearer <your-jwt-token>

Tokens are returned after login and should be stored by the client.

πŸ§ͺ Example Workflow

  1. Register or Log In

    POST /securial/accounts/register
POST /securial/sessions/login

  2. Receive JWT in the response.

  3. Use JWT in subsequent requests via:

    Authorization: Bearer <your-jwt>

  4. Call protected endpoints like:

    GET /securial/accounts/me

  5. Log out

    DELETE /securial/sessions/logout

πŸ§ͺ Testing the Endpoints

You can test Securial endpoints using:

  • cURL
  • Postman
  • HTTPie
  • Or from your frontend/mobile client

Example curl request:

$ curl -X POST http://localhost:3000/securial/sesions/login \\
  -H "Content-Type: application/json" \\
  -d '{"email_address":"[email protected]", "password":"password"}'

>
{
  "accessToken": "eyJraWQiOiJobWFjIiwiYWxnIjoiSFMyNTYifQ.eyJqdGkiOiIwMTk3MWVhZS0zYTk5LTdlNDAtOWRhZC01MDgxMzRiZWU2N2MiLCJleHAiOjE3NDg1NjY2MDQsInN1YiI6InNlc3Npb24tYWNjZXNzLXRva2VuIiwicmVmcmVzaF9jb3VudCI6MCwiaXAiOiI6OjEiLCJhZ2VudCI6ImN1cmwvOC43LjEifQ.TJH_Hhw3jroweO2ZFiFX-HEIcfl1R0t9L533reTciHs",
  "refreshToken": "84dba56cf053c33e72a75f1a255ee6bcf511fc38fc329ed0986fa1e6d36310b80d24d54e93ec76af06264eb1af293f21d1015ed794721e70a3c0274cf082babd",
  "refreshTokenExpiresAt": "2025-06-06T00:53:44.211Z"
}

🧩 Want to Customize?

Check the Configuration and Customization pages for how to override behavior and views in your host application.

Full API endpoint guide

For a full list of API guide, please see the API references.

πŸ› οΈ Securial is an open-source Rails engine maintained by @AlyBadawy.
πŸ“¦ View the source on GitHub Β· πŸ’¬ Ask questions via Discussions
πŸ“– Need help? See the FAQ or open an issue.

Gem Version

β¬… Back to Wiki Home

⚠️ **GitHub.com Fallback** ⚠️