❓ Frequently Asked Questions (FAQ)

This page addresses common questions about using and configuring the Securial Rails engine.

---

💡 What is Securial?

Securial is a mountable Rails engine that provides secure session token authentication, refresh tokens, role management and password policies for API‑driven applications. It allows you to integrate authentication quickly without reinventing the wheel.

---

🗄️ Which databases are supported?

Any ActiveRecord‑compatible database — PostgreSQL, MySQL, SQLite and others. Because Securial uses UUIDv7 string primary keys, no database extensions are required.

---

🧩 How do I install Securial?

See the Installation page for step-by-step instructions.

---

⚙️ Where do I configure Securial?

Edit config/initializers/securial.rb and set the options described on the Configuration page. Make sure you set a strong session_secret and adjust other settings like session expiry and password policies.

🗃️ How do I apply the database migrations?

When you install Securial, the migration files are copied into your host app’s db/migrate directory.

To apply the migrations:

bin/rails db:migrate

This sets up the necessary tables (users, roles, sessions, etc.) in your database.

---

🔁 How do I reset a password?

Send a POST request to /passwords/forgot_password with the user’s email. Securial sends reset instructions if the email exists. Then call /passwords/reset_password with the reset token, new password and confirmation. Tokens expire after the duration configured by reset_password_token_expires_in.

---

🔐 Can I rotate my secrets?

Yes. Changing session_secret will invalidate all existing session and refresh tokens. For zero‑downtime rotation you can support multiple secrets during the transition period.

---

🔐 How does authentication work?

Securial uses JWT-based authentication with session and refresh tokens. It supports configurable session expiration and renewal durations. See the Authentication page for more. details.

---

🔄 What happens when I change the session secret?

If you change the session_secret configuration value, all existing session tokens will become invalid. Users will need to re-authenticate.

---

👥 Can I define multiple admin roles?

Securial supports a single admin role specified by admin_role. You can create additional roles and enforce them in your own controllers, but only one role is treated as having full administrative privileges.

---

📬 Does Securial handle password reset emails?

Yes. Securial supports password reset workflows out of the box, including:

• Email delivery using your configured mailer.
• Expiring reset tokens.
• Custom email subjects and token secrets.

See the Authentication and Configuration pages for more.

---

🚨 What happens if I misconfigure something?

Securial defines a set of custom configuration errors. If required values are missing or incorrect, it will raise meaningful exceptions (e.g., ConfigSessionSecretError). See the Errors page for more.

---

🤝 How can I contribute?

We welcome contributions! Please open an issue or pull request on the GitHub repository.

---

Have more questions? Open an issue or reach out through the repository!