> ## Documentation Index
> Fetch the complete documentation index at: https://rideshare.docs.sumit-dhondikar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Sign up with OTP verification, log in to receive JWT tokens, and authorize requests using Bearer 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.

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

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

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

**Step 2 — Create your account**

Submit your credentials along with the OTP:

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "message": "Account created/updated successfully."
}
```

## Logging in

Call `POST /auth/login` with your email and password to receive tokens:

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

```json theme={null}
{
  "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:

```bash theme={null}
curl -X GET "http://localhost:8080/rides/estimate?distanceKm=5" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."
```

The token type is always `Bearer`.

<Warning>
  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.
</Warning>

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

```bash theme={null}
curl -X POST http://localhost:8080/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiJ9..."}'
```

```json theme={null}
{
  "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.

```bash theme={null}
curl -X POST http://localhost:8080/auth/logout \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiJ9..."}'
```

```json theme={null}
{
  "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:

```bash theme={null}
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

<Note>
  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          |
</Note>