attune/docs/authentication/auth-quick-reference.md

Authentication Quick Reference

Environment Variables

JWT_SECRET=your-secret-key-here              # Required in production!
JWT_ACCESS_EXPIRATION=3600                   # Optional (1 hour default)
JWT_REFRESH_EXPIRATION=604800                # Optional (7 days default)

Endpoints

Register New User

POST /auth/register
Content-Type: application/json

{
  "login": "username",
  "password": "securepass123",
  "display_name": "Full Name"  // optional
}

Login

POST /auth/login
Content-Type: application/json

{
  "login": "username",
  "password": "securepass123"
}

Refresh Token

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGc..."
}

Get Current User (Protected)

GET /auth/me
Authorization: Bearer <access_token>

Change Password (Protected)

POST /auth/change-password
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "current_password": "oldpass123",
  "new_password": "newpass456"
}

Response Format

Success (Register/Login/Refresh)

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

Success (Get Current User)

{
  "data": {
    "id": 1,
    "login": "username",
    "display_name": "Full Name"
  }
}

Error

{
  "error": "Invalid login or password",
  "code": "UNAUTHORIZED"
}

HTTP Status Codes

• 200 OK - Success
• 400 Bad Request - Invalid request format
• 401 Unauthorized - Missing/invalid/expired token or bad credentials
• 403 Forbidden - Insufficient permissions
• 409 Conflict - Username already exists
• 422 Unprocessable Entity - Validation error

Common Errors

Error	Cause	Solution
Missing authentication token	No Authorization header	Add Authorization: Bearer <token>
Invalid authentication token	Malformed or wrong secret	Verify token format and JWT_SECRET
Authentication token expired	Access token expired	Use refresh token to get new one
Invalid login or password	Wrong credentials	Check username and password
Username already exists	Duplicate registration	Use different username
Validation failed	Password too short, etc.	Check validation requirements

Validation Rules

• Login: 3-255 characters
• Password: 8-128 characters
• Display Name: 0-255 characters (optional)

cURL Examples

# Register
curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"login":"alice","password":"secure123","display_name":"Alice"}'

# Login
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"login":"alice","password":"secure123"}'

# Get Current User (replace TOKEN)
curl http://localhost:8080/auth/me \
  -H "Authorization: Bearer TOKEN"

# Change Password
curl -X POST http://localhost:8080/auth/change-password \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"current_password":"secure123","new_password":"newsecure456"}'

# Refresh Token
curl -X POST http://localhost:8080/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"REFRESH_TOKEN"}'

Using in Route Handlers

use crate::auth::middleware::RequireAuth;

async fn protected_handler(
    RequireAuth(user): RequireAuth,
) -> Result<Json<ApiResponse<Data>>, ApiError> {
    let identity_id = user.identity_id()?;
    let login = user.login();
    
    // Your handler logic
    Ok(Json(ApiResponse::new(data)))
}

Security Checklist

• Use HTTPS in production
• Set strong JWT_SECRET (256+ bits)
• Store tokens securely on client
• Implement rate limiting
• Never log tokens
• Rotate secrets periodically
• Clear tokens on logout

Token Lifecycle

1. Register/Login → Receive access + refresh tokens
2. API Call → Use access token in Authorization header
3. Token Expires → Use refresh token to get new access token
4. Refresh Expires → User must login again

Troubleshooting

Server won't start?

• Check DATABASE_URL is set
• Verify database is running
• Run migrations: sqlx migrate run

Auth fails with valid credentials?

• Check password hash in database
• Verify JWT_SECRET matches
• Check token expiration

Debug logging:

RUST_LOG=attune_api=debug cargo run --bin attune-api

Documentation

• Full docs: docs/authentication.md
• Testing guide: docs/testing-authentication.md
• Implementation: crates/api/src/routes/auth.rs