Skip to main content
The RideShare API uses JWT-based authentication. To access protected endpoints, you must first create an account and log in to receive an access token.

​
Signup flow

Account creation requires email verification via a one-time passcode (OTP). Step 1 — Request an OTP Send your name and email to receive a passcode: 
curl -X POST http://localhost:8080/auth/signup/request-otp \
  -H "Content-Type: application/json" \
  -d '{"name": "Your Name", "email": "you@example.com"}'

{
  "message": "OTP sent successfully.",
  "emailSent": true,
  "expiresAt": "2026-04-02T10:15:00Z"
}
Step 2 — Create your account Submit your credentials along with the OTP: 
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"
  }'

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

​
Logging in

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

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

​
Authorizing requests

Include your access token in the Authorization header on every request to a protected endpoint: 
curl -X GET "http://localhost:8080/rides/estimate?distanceKm=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."
The token type is always Bearer.
Access tokens expire after expiresIn seconds (3600 seconds by default). Once expired, requests will be rejected with a 401 response. Use your refresh token to get a new access token before it expires.

​
Refreshing tokens

Call POST /auth/refresh with your current refresh token to receive a new access token and a rotated refresh token. The old refresh token is immediately invalidated. 
curl -X POST http://localhost:8080/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiJ9..."}'

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "id": 42,
  "name": "Your Name",
  "role": "USER"
}
Store the new refreshToken returned in the response. Your previous refresh token will no longer work.

​
Logging out

Call POST /auth/logout with your refresh token to revoke it. After logout, the refresh token cannot be used to issue new access tokens. 
curl -X POST http://localhost:8080/auth/logout \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiJ9..."}'

{
  "message": "Logged out."
}

​
Roles

Your account has a role that controls what actions you can perform. The supported roles are:
RoleDescription
USERDefault role. Can book rides, view history, and manage account settings.
RIDERCan request and track rides as a passenger.
DRIVERCan accept ride requests, update location, and manage driver status.
ADMINFull access to all endpoints including administrative operations.
By default, your account is assigned the role you specified at signup (or USER if none was provided). You can request a specific role at login time by including the role field in your login request body: 
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password",
    "role": "DRIVER"
  }'
If you request a role that is not valid, the API falls back to the role stored on your account.

​
Public vs. protected endpoints

The following endpoints do not require an Authorization header. All other endpoints require a valid Bearer token.
EndpointMethodDescription
/auth/signup/request-otpPOSTRequest an OTP for email verification
/auth/signupPOSTCreate or update an account
/auth/loginPOSTLog in and receive tokens
/auth/refreshPOSTRotate tokens using a refresh token
/auth/logoutPOSTRevoke a refresh token
/rides/estimateGETGet a fare estimate
/rides/drivers/nearbyGETFind nearby available drivers
/rides/status/{rideId}GETGet the current status of a ride
/rides/requestedGETList all open ride requests
/payments/verifyPOSTVerify a payment signature
/payments/session/{sessionId}GETCheck payment session status