Quick start

All examples in this guide use the development base URL http://localhost:8080. Replace this with your production base URL when you deploy.

Request an OTP

Before creating an account, verify your email address by requesting a one-time passcode.

curl -X POST http://localhost:8080/auth/signup/request-otp \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "Your Name"}'

A successful response confirms that the OTP was generated and sent to your email:

{
  "message": "OTP sent successfully.",
  "emailSent": true,
  "expiresAt": "2026-04-02T10:15:00Z"
}

Create your account

Submit your name, email, password, and the OTP you received to create an account.

curl -X POST http://localhost:8080/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Name",
    "email": "you@example.com",
    "password": "your-password",
    "otp": "123456"
  }'

A successful response confirms account creation:

{
  "message": "Account created/updated successfully."
}

curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

Save the accessToken and refreshToken from the response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "id": 42,
  "name": "Your Name",
  "role": "USER"
}

Use the accessToken to authorize subsequent requests. When it expires, use the refreshToken to get a new one — see Authentication for details.

Make an authenticated request

Pass the access token in the Authorization header on every authenticated request. This example fetches a fare estimate for a 5 km trip.

curl -X GET "http://localhost:8080/rides/estimate?distanceKm=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

Get Started

Core Concepts

Guides