Hi folks👋!
In this post I want to share something I wish I had when I started building APIs with Ruby on Rails: a practical guide that takes security seriously from the beginning.
When I built my first REST API, most tutorials I found were focused on getting something running quickly. They were great for learning the basics, but they usually skipped important topics like API versioning, authentication strategy, authorization, and security.
Even when using AI tools to generate a “secure API”, the result is often still insecure unless you already understand the threats you are trying to protect against. Security is not something you get automatically. You need to know what problems you are solving and why the protections matter.
I ended up reading API design books, OWASP documentation, and real-world breach reports before I finally felt like I understood what I was building, I've put all in practice. This post is the guide I wish I had back then.
In this series we are going to build a production-ready Rails 8 API with authentication, authorization, rate limiting, secure cookies, security headers, and other important protections. I also want to explain the reasoning behind each decision, not just copy-paste code without context.
Before writing any code, let’s first understand the main attack vectors we need to defend against.
The attack vectors we are defending against
1. XSS (Cross-Site Scripting)
🚨 Threat:
XSS happens when an attacker injects malicious JavaScript into content that later gets rendered in another user’s browser. In API-driven applications, one of the biggest risks is token theft. If JWTs are stored in localStorage, a malicious script can read and steal them immediately.
🛡️ Mitigation:
Avoid storing authentication tokens in localStorage or other browser-accessible storage. Instead, store them in secure HttpOnly cookies so JavaScript cannot access them. Cookies should also use the Secure and SameSite attributes. Any user-generated content rendered in the frontend should be properly escaped or sanitized.
2. SQL Injection
🚨 Threat:
SQL Injection happens when user input is inserted directly into a SQL query without proper sanitization. An attacker can manipulate the query to bypass authentication, read sensitive data, or modify the database.
🛡️ Mitigation:
Avoid interpolating user input directly into SQL queries. In Rails, prefer Active Record methods like where, find_by, and parameterized queries, which automatically sanitize input. If raw SQL is unavoidable, use bound parameters instead of string interpolation. You should also validate input, use strong parameters, and follow the principle of least privilege for database accounts.
3. CSRF (Cross-Site Request Forgery)
🚨 Threat:
CSRF happens when a malicious website tricks a logged-in user’s browser into sending authenticated requests to your application using automatically attached cookies.
This is especially important in Rails APIs using session cookies or JWTs stored in HttpOnly cookies. Even though JavaScript cannot read those cookies, the browser still sends them automatically with requests.
An attacker could potentially trigger actions like changing account settings, creating resources, or deleting data without the user realizing it.
🛡️ Mitigation:
Enable CSRF protection for any cookie-based authentication flow. In Rails, use protect_from_forgery and require valid CSRF tokens for state-changing requests like POST, PUT, PATCH, and DELETE.
Authentication cookies should also use:
HttpOnlySecureSameSite=LaxorSameSite=Strict
You should also validate Origin and Referer headers and keep CORS restricted to trusted frontend domains.
If the browser automatically sends authentication, CSRF protection still matters, even if the API itself is technically stateless.
4. Brute Force
🚨 Threat:
Brute force attacks happen when an attacker repeatedly tries large numbers of username and password combinations against your login endpoint.
This commonly targets login forms, password reset endpoints, and authentication APIs. Successful attacks can lead to account compromise, credential stuffing, and unnecessary server load.
🛡️ Mitigation:
Use rate limiting on authentication-related endpoints. In Rails, tools like Rack::Attack can throttle repeated requests by IP address, email, or both.
You should also:
temporarily lock accounts after repeated failures
require strong passwords
detect suspicious login activity
avoid revealing whether an account exists
consider CAPTCHA or step-up verification after suspicious behavior
5. User Enumeration
🚨 Threat:
User enumeration happens when an application reveals whether an account exists through different error messages.
For example:
“Email not found”
“Incorrect password”
An attacker can use these differences to discover valid accounts and later target them with brute force attacks, phishing, or credential stuffing.
🛡️ Mitigation:
Return consistent responses during login, password reset, and account recovery flows.
Instead of exposing whether the email exists, use generic responses such as:
“Invalid credentials”
“If an account exists, instructions have been sent”
You should also rate limit these endpoints and monitor repeated probing attempts.
6. IDOR (Insecure Direct Object Reference)
🚨 Threat:
IDOR happens when users can access resources they do not own by changing identifiers in URLs or request parameters.
For example:
User.find(params[:id])
If ownership checks are missing, changing /users/42 to /users/43 could expose another user’s data.
🛡️ Mitigation:
Always scope records through the authenticated user or an authorization policy.
Instead of:
Post.find(params[:id])
Prefer:
current_user.posts.find(params[:id])
Authorization libraries like Pundit or CanCanCan also help enforce access rules consistently across the application. I also avoid exposing raw database IDs directly to the frontend. Instead, I use Sqidsto generate less predictable public IDs, which helps reduce simple enumeration attacks.
7. Mass Assignment
🚨 Threat:
Mass assignment happens when the application accepts user input and blindly assigns it to model attributes.
An attacker could submit unexpected fields such as:
{
"admin": true
}
If those fields are not filtered properly, the attacker may gain elevated privileges or modify protected data.
🛡️ Mitigation:
Use strong parameters in every controller.
In Rails, always whitelist allowed attributes using:
params.require(:user).permit(:email, :password)
Never pass raw params directly into create or update.
Sensitive fields like roles, permissions, ownership fields, or account status flags should never be user-assignable.
8. Excessive Data Exposure
🚨 Threat:
Excessive data exposure happens when an API returns more information than the client actually needs.
This often happens when entire Active Record objects are rendered directly into JSON responses.
Sensitive data such as password digests, internal IDs, permissions, API keys, or private metadata may accidentally leak through the API.
🛡️ Mitigation:
Only return the fields the client actually needs.
Instead of blindly rendering full objects:
render json: @user
Use serializers or custom JSON responses that explicitly define safe attributes.
Sensitive fields should never appear in API responses.
You should also regularly review serialized responses to make sure no internal data is leaking unintentionally.
9. MITM (Man-in-the-Middle)
🚨 Threat:
A Man-in-the-Middle attack happens when an attacker intercepts traffic between the client and server.
Without HTTPS, credentials, tokens, cookies, and other sensitive data can travel in plain text and be stolen or modified.
Attackers on the same network, malicious proxies, or compromised routers can hijack sessions or impersonate users.
🛡️ Mitigation:
Always enforce HTTPS.
In Rails, enable:
config.force_ssl = true
This redirects insecure requests and ensures cookies are only sent over encrypted connections.
Authentication cookies should also use the Secure and HttpOnly flags.
You should additionally enable HSTS headers and avoid loading insecure mixed-content resources.
10. Token Theft
🚨 Threat:
Token theft happens when an attacker gains access to a valid authentication token and uses it to impersonate a user.
Stolen JWTs can come from XSS attacks, insecure storage, leaked logs, browser extensions, compromised devices, or intercepted traffic.
If tokens remain valid for a long time, the attacker may keep access even after the user notices something is wrong.
🛡️ Mitigation:
Reduce token exposure and keep token lifetimes short.
Prefer storing tokens in secure HttpOnly cookies instead of localStorage.
Use:
short-lived access tokens
refresh token rotation
token revocation mechanisms
You should also avoid exposing tokens in logs or URLs and protect the application against XSS vulnerabilities.
11. Verbose Error Messages
🚨 Threat:
Verbose error messages expose internal application details to attackers.
Stack traces, database errors, framework versions, SQL queries, and file paths can all help attackers understand how the system works and make exploitation easier.
🛡️ Mitigation:
Production applications should return generic and safe error responses.
Instead of exposing internal exceptions, return messages such as:
Internal Server ErrorInvalid request
Detailed errors should only be logged internally for debugging.
In Rails, make sure debug pages and detailed exceptions are disabled in production.
Final Thoughts
These are some of the most important security risks to think about when building APIs, and we will revisit them throughout this series as we implement each feature step by step.
In Part 2 we will start building the Rails 8 API from scratch and set up the project foundation correctly from the beginning, including authentication, secure configuration, and API structure.
Follow along if you want to get notified when the next part is published.