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

# Login

> Authenticate with email and password to receive a JWT access token and refresh token.

Authenticate an existing account using an email and password. A successful response includes a short-lived access token and a longer-lived refresh token you can use to obtain new access tokens without re-entering credentials.

## Request

**`POST /auth/login`**

<ParamField body="email" type="string" required>
  The email address of the account.
</ParamField>

<ParamField body="password" type="string" required>
  The account password.
</ParamField>

<ParamField body="role" type="string">
  Override the session role for this login. Accepted values: `USER`, `RIDER`, `DRIVER`, `ADMIN`. Falls back to the role stored on the account if omitted or unrecognized.
</ParamField>

## Response

<ResponseField name="accessToken" type="string">
  A signed JWT to include in the `Authorization: Bearer <token>` header of subsequent requests.
</ResponseField>

<ResponseField name="refreshToken" type="string">
  A token you can exchange for a new access token via [Refresh Token](/api-reference/auth/refresh).
</ResponseField>

<ResponseField name="tokenType" type="string">
  Always `"Bearer"`.
</ResponseField>

<ResponseField name="expiresIn" type="number">
  Number of seconds until the access token expires.
</ResponseField>

<ResponseField name="name" type="string">
  The display name of the authenticated user.
</ResponseField>

<ResponseField name="role" type="string">
  The effective role for this session.
</ResponseField>

<ResponseField name="id" type="number">
  The numeric ID of the authenticated user.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:8080/auth/login \
    -H "Content-Type: application/json" \
    -d '{"email": "alex@example.com", "password": "s3cur3P@ss"}'
  ```

  ```json Response theme={null}
  {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
    "tokenType": "Bearer",
    "expiresIn": 900,
    "name": "Alex",
    "role": "USER",
    "id": 42
  }
  ```
</CodeGroup>

<Warning>
  Store the `refreshToken` securely (for example, in an HttpOnly cookie or secure storage). You need it to obtain a new access token once the current one expires. Never expose it in client-side JavaScript or logs.
</Warning>

## Error codes

| Status | Meaning                                                            |
| ------ | ------------------------------------------------------------------ |
| 400    | `email` or `password` is missing                                   |
| 401    | No account found for the given email, or the password is incorrect |