Authentication

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. 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:

Role	Description
`USER`	Default role. Can book rides, view history, and manage account settings.
`RIDER`	Can request and track rides as a passenger.
`DRIVER`	Can accept ride requests, update location, and manage driver status.
`ADMIN`	Full 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.

Endpoint	Method	Description
`/auth/signup/request-otp`	`POST`	Request an OTP for email verification
`/auth/signup`	`POST`	Create or update an account
`/auth/login`	`POST`	Log in and receive tokens
`/auth/refresh`	`POST`	Rotate tokens using a refresh token
`/auth/logout`	`POST`	Revoke a refresh token
`/rides/estimate`	`GET`	Get a fare estimate
`/rides/drivers/nearby`	`GET`	Find nearby available drivers
`/rides/status/{rideId}`	`GET`	Get the current status of a ride
`/rides/requested`	`GET`	List all open ride requests
`/payments/verify`	`POST`	Verify a payment signature
`/payments/session/{sessionId}`	`GET`	Check payment session status

Get Started

Core Concepts

Guides

Logging in

Authorizing requests

Refreshing tokens

Logging out

Roles

Public vs. protected endpoints

​Signup flow

​Logging in

​Authorizing requests

​Refreshing tokens

​Logging out

​Roles

​Public vs. protected endpoints

Signup flow

Logging in

Authorizing requests

Refreshing tokens

Logging out

Roles

Public vs. protected endpoints