Skip to main content

​
Overview

The Auth Service provides user authentication and authorization using JWT tokens signed with RSA keys. It supports user registration, login, and token verification.

​
Authentication Flow

  1. Signup - Register a new user with email and password
  2. Login - Authenticate and receive a JWT token
  3. Verify - Validate JWT tokens for protected resources

​
Base URL

http://auth-service:8090

​
Endpoints

​
Health Check

curl -X GET http://auth-service:8090/healthz

ok
Checks the health status of the auth service and database connection. Response Codes:
  • 200 - Service is healthy
  • 503 - Database health check failed

​
Get JWKS (JSON Web Key Set)

curl -X GET http://auth-service:8090/.well-known/jwks.json

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "abc123...",
      "n": "xGOr...",
      "e": "AQAB"
    }
  ]
}
Returns the public keys used to verify JWT tokens. Used for validating tokens signed by this service.
​
keys
array
required
Array of JSON Web Keys
​
kty
string
Key type (RSA)
​
use
string
Public key use (sig for signature)
​
alg
string
Algorithm (RS256)
​
kid
string
Key ID for identifying the signing key
​
n
string
RSA modulus
​
e
string
RSA public exponent

​
Register User

curl -X POST http://auth-service:8090/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

{
  "id": 1,
  "email": "[email protected]",
  "role": "user"
}
Creates a new user account. Passwords are hashed using bcrypt before storage.
​
email
string
required
User’s email address (must be unique)
​
password
string
required
User’s password (will be hashed with bcrypt)
​
id
integer
Unique user ID
​
email
string
User’s email address
​
role
string
User’s role (default: “user”)
Response Codes:
  • 201 - User created successfully
  • 400 - Missing required fields
  • 409 - Email already exists
  • 500 - Server error
  • 503 - Database not configured

​
Login

curl -X POST http://auth-service:8090/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFiYzEyMyJ9..."
}
Authenticates a user and returns a JWT token. The token is valid for 24 hours and is signed using RS256 algorithm.
​
email
string
required
User’s email address
​
password
string
required
User’s password
​
token
string
JWT token signed with RS256 algorithm. Contains claims:
  • sub - User ID (or email if database unavailable)
  • role - User’s role
  • iss - Issuer (auth-service)
  • exp - Expiration time (24 hours)
  • kid - Key ID for verification
Response Codes:
  • 200 - Login successful, token returned
  • 400 - Missing required fields
  • 401 - Invalid credentials
  • 500 - Server error
Note: If the database is not configured, a simplified token is issued with the email as the subject.

​
Verify Token

curl -X GET http://auth-service:8090/verify \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFiYzEyMyJ9..."

{
  "ok": true,
  "userId": "1"
}
Validates a JWT token and returns the user ID. Sets the X-User-Id header in the response.
​
Authorization
string
required
Bearer token in the format: Bearer <token>
​
ok
boolean
Always true for successful verification
​
userId
string
User ID extracted from the token’s sub claim
Response Headers:
  • X-User-Id - User ID from the token
Response Codes:
  • 200 - Token is valid
  • 401 - Missing or invalid token
Token Validation:
  • Algorithm must be RS256
  • Issuer must be “auth-service”
  • Token must not be expired
  • Signature must be valid

​
JWT Token Structure

Tokens issued by the auth service contain the following claims: 
{
  "sub": "1",              // User ID (subject)
  "role": "user",          // User role
  "iss": "auth-service",   // Issuer
  "exp": 1234567890,       // Expiration timestamp
  "iat": 1234567890        // Issued at timestamp
}
The token header includes: 
{
  "alg": "RS256",          // Algorithm
  "typ": "JWT",            // Token type
  "kid": "abc123..."       // Key ID for verification
}

​
Error Handling

All error responses follow this format: 
{
  "error": "error description"
}
Common HTTP status codes:
  • 400 - Bad Request (missing or invalid parameters)
  • 401 - Unauthorized (authentication failed)
  • 409 - Conflict (duplicate email)
  • 500 - Internal Server Error
  • 503 - Service Unavailable (database issues)

​
Security Notes

  1. Password Hashing: All passwords are hashed using bcrypt with 10 salt rounds
  2. Token Signing: JWT tokens are signed using RSA-SHA256 (RS256)
  3. Token Expiration: Tokens expire after 24 hours
  4. Key Management: RSA key pairs are generated at startup (development mode). In production, keys should be loaded from Kubernetes Secrets
  5. CORS: Cross-Origin Resource Sharing is enabled for all origins

Build docs developers (and LLMs) love

Get started for freeTalk to us