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

# Authentication overview

> API reference for authentication and authorization

## Overview

The Authentication API provides secure user authentication with support for:

* Username/password authentication
* Multi-factor authentication (2FA)
* JWT token management
* API key authentication

## Authentication Flow

### 1. Initial Authentication

```http theme={null}
POST /v1/authenticate
Content-Type: application/json

{
  "username": "user@example.com",
  "password": "secure_password"
}
```

**Response Options:**

a) Direct Authentication Success:

```json theme={null}
{
  "access_token": "eyJhbGciOi...",
  "expires_in": 900,
  "user_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

b) When MFA is required:

```json theme={null}
{
  "credential_type": "phone",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "An OTP has been sent to your phone successfully."
}
```

### 2. Verify 2FA (if required)

```http theme={null}
POST /v1/verify-2fa
Content-Type: application/json

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "otp": "123456"
}
```

## Token Management

* **Access Token**: 15-minute lifespan, sent in Authorization header
* **Refresh Token**: 14-day lifespan, stored as HTTP-only cookie
* **Token Format**: `Authorization: Bearer <token>`

### Refresh Access Token

```http theme={null}
POST /v1/refresh-token
X-Device-ID: 16be137a-f9b1-4830-8828-f5a51038918e
```

## Security Features

* Brute force protection
* IP-based rate limiting
* Device tracking
* Secure token rotation
* HTTP-only cookies for refresh tokens

## Required Headers

| Header        | Description              | When to Use                                                                 |
| ------------- | ------------------------ | --------------------------------------------------------------------------- |
| Authorization | `Bearer <token>`         | Required for all authenticated endpoints except login and self-registration |
| X-Device-ID   | Unique device identifier | Required for all authentication requests                                    |

<Note>
  The Authorization header is not needed for `/v1/authenticate` since this endpoint issues the token.
</Note>