Overview The CryptoPulse API uses JWT (JSON Web Token) bearer authentication to protect price endpoints. Authentication is required for all /v1/price/* endpoints.
Authentication Flow
Login : Send credentials to /auth/loginReceive Token : Get a JWT access token in the responseUse Token : Include token in Authorization header for protected endpointsToken Expiry : Request a new token when the current one expires
Login Endpoint Request POST /auth/logincurl -X POST http://localhost:3000/auth/login \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "secret" }'
Request Body Field Type Required Description username string Yes Admin username (configured via ADMIN_USER env var) password string Yes Admin password (configured via ADMIN_PASS env var)
Response Status : 200 OK{ "accessToken" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsInVzZXJuYW1lIjoiYWRtaW4ifQ.signature" , "tokenType" : "Bearer" , "expiresIn" : "1h" }
Response Fields Field Type Description accessToken string JWT token to use for authentication tokenType string Always “Bearer” expiresIn string Token validity duration (e.g., “1h”, “30m”)
The API issues standard JWT tokens with the following structure:
{ "alg" : "HS256" , "typ" : "JWT" }
Payload { "sub" : "admin" , "username" : "admin" , "iat" : 1709093700 , "exp" : 1709097300 }
Signature The token is signed using the JWT_SECRET environment variable with HMAC SHA256.
Using Bearer Tokens To access protected endpoints, include the JWT token in the Authorization header:
Authorization: Bearer <your-access-token>
Example Request curl -X GET http://localhost:3000/v1/price/bitcoin \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Code Examples const axios = require ( 'axios' ); // Login const loginResponse = await axios . post ( 'http://localhost:3000/auth/login' , { username: 'admin' , password: 'secret' }); const { accessToken } = loginResponse . data ; // Use token for authenticated request const priceResponse = await axios . get ( 'http://localhost:3000/v1/price/bitcoin' , { headers: { 'Authorization' : `Bearer ${ accessToken } ` } }); console . log ( priceResponse . data );
Token Expiry Default Expiration Tokens expire after 1 hour by default. This can be configured using the JWT_EXPIRES_IN environment variable.
Configuration Options The expiresIn field supports various time formats:
"1h" - 1 hour"30m" - 30 minutes"7d" - 7 days"3600" - 3600 seconds
Handling Expiration When a token expires, protected endpoints return a 401 Unauthorized error:
{ "statusCode" : 401 , "message" : "Invalid or expired token" , "error" : "Unauthorized" }
Solution : Request a new token by calling /auth/login again.Rate Limiting The login endpoint has stricter rate limits to prevent brute force attacks:
Limit : 5 requests per 60 seconds (configurable via THROTTLE_LOGIN_LIMIT)Window : 60 seconds (configurable via THROTTLE_TTL_MS)
Rate Limit Error { "statusCode" : 429 , "message" : "ThrottlerException: Too Many Requests" , "error" : "Too Many Requests" }
Error Responses Invalid Credentials Status : 401 Unauthorized{ "statusCode" : 401 , "message" : "Invalid credentials" , "error" : "Unauthorized" }
Status : 401 Unauthorized{ "statusCode" : 401 , "message" : "Missing Authorization header" , "error" : "Unauthorized" }
Status : 401 Unauthorized{ "statusCode" : 401 , "message" : "Authorization header must use Bearer token" , "error" : "Unauthorized" }
Malformed Request Body Status : 400 Bad Request{ "statusCode" : 400 , "message" : [ "username should not be empty" , "password must be a string" ], "error" : "Bad Request" }
Security Best Practices Never expose your JWT_SECRET, ADMIN_USER, or ADMIN_PASS environment variables in client-side code or public repositories.
Recommendations
Store tokens securely : Use secure storage mechanisms (e.g., httpOnly cookies, secure localStorage)Use HTTPS : Always use HTTPS in production to prevent token interceptionRotate secrets : Regularly rotate your JWT_SECRET and admin credentialsMonitor failed logins : Track failed authentication attemptsImplement token refresh : Consider implementing refresh tokens for long-lived sessionsSet appropriate expiry : Balance security and user experience with token expiration times
Environment Configuration Authentication behavior is controlled by these environment variables:
Variable Required Default Description ADMIN_USERYes - Login username ADMIN_PASSYes - Login password JWT_SECRETYes - Secret key for signing JWT tokens JWT_EXPIRES_INNo 1hToken expiration time THROTTLE_TTL_MSNo 60000Rate limit window in milliseconds THROTTLE_LOGIN_LIMITNo 5Max login attempts per window
Next Steps
Get Price Use your token to fetch cryptocurrency prices
Price History Query historical price data