Step 4.1 – Rails API structure and first endpoint
Before building Task CRUD endpoints, let’s establish our API structure and see how Rails handles HTTP requests.
One important decision: We’ll implement JWT authentication before exposing task data. I don’t want us to build an endpoint that returns every user’s tasks and later re-fit authorization.
Understand our API structure
We’ll use versioned API namespaces.
backend/
├── app/
│ ├── controllers/
│ │ ├── application_controller.rb
│ │ └── api/
│ │ └── v1/
│ │ └── health_controller.rb
│ │
│ ├── models/
│ │ ├── user.rb
│ │ └── task.rb
│ │
│ └── ...
│
├── config/
│ └── routes.rb
│
└── spec/
├── models/
└── requests/
└── api/
└── v1/
Why version the API?
Suppose we eventually release our API to external consumers. We might introduce breaking changes in the future.
/api/v1/tasks
/api/v2/tasks
We can maintain both versions during a migration rather than breaking existing clients.
Understand JWT architecture
JWT stands for JSON Web Token. It is a compact format for securely transmitting claims between parties.
A JWT consists of three parts:

Header example
{
"alg": "HS256",
"typ": "JWT"
}
Payload example
{
"sub": "42",
"iss": "task_manager_api",
"aud": "task_manager_web",
"iat": 1795000000,
"exp": 1795000600,
"jti": "unique-token-id"
}
Signature: Generated using the encoded header, encoded payload and signing secret. It allows Rails to detect token modification.
The complete token looks like: xxxxx.yyyyy.zzzzz
Each part is Base64URL encoded, and the signature is cryptographically generated.
Important: JWT is not encrypted by default. Anyone who obtains a JWT can decode its header and payload. The signature protects integrity, not confidentiality. Never put passwords or sensitive personal information in the payload.
Understand the claims we will use
Claims are the information carried inside the JWT payload.
| Claim | Meaning | Our usage |
|---|---|---|
sub | Subject | User ID |
iss | Issuer | Our Rails API |
aud | Audience | Our React application |
iat | Issued at | Token creation time |
exp | Expiration | Token expiry |
jti | JWT ID | Unique token identifier |
Two important concepts:
sub – Subject – Identifies the user associated with the token.
We’ll use: {
"sub": "42"
}
When Rails receives the token, it can identify user ID 42 after verifying the signature.
exp – Expiration – Defines when the access token expires.
Our initial policy:
10 min – Access token lifetime – Short-lived JWT
7 days – Refresh session lifetime – Initial policy, configurable
We’ll implement refresh-token expiration and rotation separately.
Which signing algorithm should we use?
We’ll start with HS256.
| Algorithm | Description |
|---|---|
| HS256 | HMAC using SHA-256 and a shared secret |
| RS256 | RSA with SHA-256, using private/public keys |
| ES256 | ECDSA with SHA-256 |
Why HS256?
Our architecture currently has one Rails application that both generates and verifies tokens.
- Rails has the signing secret.
- Rails verifies signatures using the same secret.
- We don’t need public/private key infrastructure yet.
One security rule: the verification algorithm must be explicitly allowlisted. Never trust the alg value supplied in an unverified token header to choose the verification algorithm.
Q) Why use JWT? How we trust the JWT payload/header? JWT vs Opaque token
Read detail here(Premium Content): https://railsdrop.com/why-use-jwt-how-we-trust-the-jwt-payload-header/