> ## Documentation Index
> Fetch the complete documentation index at: https://dvaultdocs.dukka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API authentication and security

# Authentication API Documentation

## Overview

The Authentication API provides endpoints for user authentication, password management, and token refresh functionality.

## Base URL

`/api/v1/auth`

## Authentication

Most endpoints require authentication using an API key in the request headers:

* `X-API-KEY`: Your API key

## Endpoints

### Login

Authenticates a user and returns access and refresh tokens.

**Endpoint:** `POST /login`

**Request Body:**

```json theme={null}
{
  "email": "string",
  "password": "string",
  "rememberMe": boolean
}
```

**Response:**

```json theme={null}
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "response": {
      "accessToken": "string",
      "user": {
        "userId": "string",
        "email": "string",
        "firstName": "string",
        "lastName": "string",
        "type": "string",
        "tenant": {
          "tenantId": "string",
          "name": "string"
        }
      }
    }
  }
}
```

**Notes:**

* The refresh token is returned as an HTTP-only cookie
* If `rememberMe` is true, the refresh token cookie will have a longer expiration time
* The cookie is secure and SameSite=None to prevent CSRF attacks

### Forgot Password

Initiates the password reset process by sending an OTP to the user's email.

**Endpoint:** `GET /forgot-password/{email}`

**Path Parameters:**

* `email`: User's email address

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "If this email is registered, a password reset OTP has been sent",
  "data": "string"
}
```

### Change Password

Changes the user's password using the OTP received from the forgot password process.

**Endpoint:** `POST /change-password`

**Request Body:**

```json theme={null}
{
  "email": "string",
  "newPassword": "string",
  "otp": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "userId": "string",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "type": "string",
    "tenant": {
      "tenantId": "string",
      "name": "string"
    }
  }
}
```

### Refresh Token

Refreshes the access token using the refresh token from the cookie.

**Endpoint:** `GET /refresh-token`

**Cookies:**

* `refreshToken`: The refresh token received during login

**Response:**

```json theme={null}
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "response": {
      "accessToken": "string",
      "user": {
        "userId": "string",
        "email": "string",
        "firstName": "string",
        "lastName": "string",
        "type": "string",
        "tenant": {
          "tenantId": "string",
          "name": "string"
        }
      }
    }
  }
}
```

**Notes:**

* A new refresh token is returned as an HTTP-only cookie
* The cookie is secure and SameSite=None to prevent CSRF attacks

### Setup Password

Sets up the initial password for a user.

**Endpoint:** `POST /setup-password`

**Headers:**

* `X-API-KEY`: API key for authentication

**Request Body:**

```json theme={null}
{
  "password": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "password setup successfully",
  "data": "string"
}
```

## Error Responses

All endpoints may return the following error responses:

**401 Unauthorized**

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
```

**404 Not Found**

```json theme={null}
{
  "statusCode": 404,
  "message": "Resource not found",
  "data": null
}
```

**409 Conflict**

```json theme={null}
{
  "statusCode": 409,
  "message": "User already has a password",
  "data": null
}
```

## Notes

* All passwords must meet the system's security requirements
* OTPs expire after 10 minutes
* Refresh tokens are stored as HTTP-only cookies for security
* Access tokens should be included in the Authorization header for protected endpoints
* Tenant users cannot set up passwords