Skip to main content

​
Overview

TerraQuake API uses JWT (JSON Web Token) authentication for protected endpoints. Most endpoints are public and don’t require authentication, making it easy to get started immediately.
Public endpoints like /earthquakes/* and /stations/* don’t require authentication. You can start querying earthquake data right away!

​
Public vs Protected Endpoints

​
Public Endpoints (No Authentication Required)

These endpoints are accessible without any authentication:
  • All Earthquake Endpoints: /earthquakes/recent, /earthquakes/today, /earthquakes/magnitude, etc.
  • All Station Endpoints: /stations, /stations/code, /stations/geojson, etc.
  • Most Utility Endpoints: Statistics, FAQs, documentation, etc.

​
Protected Endpoints (Authentication Required)

These endpoints require a valid JWT token:
  • User Profile: GET /auth/me - Get current user information
  • Logout: POST /auth/logout - Invalidate current session
  • Change Password: POST /auth/change-password - Update user password
  • Admin Endpoints: All endpoints under /admin/* (requires admin role)

​
Getting Started with Authentication

1

Create an Account

Register for an account using the signup endpoint:
curl -X POST https://api.terraquakeapi.com/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password",
    "name": "Your Name"
  }'
You’ll receive a confirmation email after registration. Check your inbox to verify your account.
2

Sign In

Once your account is verified, sign in to get your JWT token:
curl -X POST https://api.terraquakeapi.com/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }'
Response:
{
  "success": true,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "_id": "507f1f77bcf86cd799439011",
    "email": "[email protected]",
    "name": "Your Name",
    "role": ["user"]
  }
}
Store the token securely. Never expose it in client-side code or commit it to version control.
3

Use the Token

Include the JWT token in the Authorization header for protected endpoints:
curl https://api.terraquakeapi.com/auth/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Token Validation

When you make a request to a protected endpoint, the API validates your token through these checks:
  1. Token Presence: The Authorization header must include a valid token
  2. Token Format: Must be in the format Bearer <token>
  3. Signature Verification: Token signature is verified using the secret key
  4. Expiration Check: Token must not be expired
  5. Blacklist Check: Token must not be revoked (e.g., after logout)
  6. User Validation: User account must exist and be active
Token validation is handled by the authentication middleware at /home/daytona/workspace/source/backend/src/middleware/authMiddleware.js:11

​
Error Responses

The API returns specific error messages for authentication failures:

​
Missing Token

{
  "success": false,
  "message": "Authorization token missing",
  "statusCode": 401
}

​
Invalid or Expired Token

{
  "success": false,
  "message": "Invalid, expired, or revoked token. Please log in again.",
  "statusCode": 401
}

​
User Not Found

{
  "success": false,
  "message": "User account not found or has been deleted.",
  "statusCode": 404
}

​
Malformed Token

{
  "success": false,
  "message": "Malformed or invalid token",
  "statusCode": 401
}

​
Password Management

​
Change Password

Update your password while authenticated:
cURL
curl -X POST https://api.terraquakeapi.com/auth/change-password \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "old-password",
    "newPassword": "new-secure-password"
  }'

​
Forgot Password

Request a password reset link:
cURL
curl -X POST https://api.terraquakeapi.com/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'
You’ll receive an email with a reset token.

​
Reset Password

Reset your password using the token from the email:
cURL
curl -X POST https://api.terraquakeapi.com/auth/reset-password/RESET_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "newPassword": "new-secure-password"
  }'

​
Logout

Invalidate your current session token:
cURL
curl -X POST https://api.terraquakeapi.com/auth/logout \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
After logout, the token is added to a blacklist and cannot be used again. You must sign in again to get a new token.

​
OAuth Authentication

TerraQuake API also supports OAuth authentication with Google:

​
Google Sign-In Flow

  1. Redirect to Google: Direct users to /auth/google
  2. Handle Callback: After user grants permission, Google redirects to /auth/google/callback
  3. Receive Token: The API returns a JWT token for the authenticated user
Example: Google OAuth
// Step 1: Redirect user to Google
window.location.href = 'https://api.terraquakeapi.com/auth/google';

// Step 2: Handle callback (Google redirects back)
// The callback URL will include the JWT token
OAuth is great for applications where you want to avoid managing user passwords directly.

​
Best Practices

Secure Storage

Store tokens securely in environment variables or secure storage (e.g., httpOnly cookies)

Token Refresh

Sign in again when tokens expire rather than storing long-lived tokens

HTTPS Only

Always use HTTPS when transmitting tokens to prevent interception

Logout Properly

Always call the logout endpoint when users sign out to invalidate tokens

​
Next Steps

Error Handling

Learn how to handle authentication errors gracefully

API Reference

Explore all available endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us