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

# Authentication

> Secure API access with API keys, MFA, and session management

# Authentication

Fincept API uses API key authentication to secure all requests. This guide covers registration, API key management, security best practices, and multi-factor authentication.

## API Key Types

### Registered User Keys

Permanent API keys with full access to all features and credit management.

**Format:** `fk_user_` followed by a secure random string

**Features:**

* Permanent access (never expires)
* Full tier access based on subscription
* Credit balance and top-up management
* Usage analytics and history
* Multi-factor authentication support
* API key regeneration
* Session management

\###Guest Keys

Temporary 24-hour keys for testing and evaluation.

**Format:** `fk_guest_` followed by a secure random string

**Features:**

* 24-hour validity
* Free tier access only
* 50 credits for testing
* No credit top-up
* No persistent storage after expiry
* Limited to 50 requests/day

## Getting Started

### Register a New Account

Create a permanent user account:

```bash theme={null}
curl -X POST https://api.fincept.in/user/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "email": "your@email.com",
    "password": "SecurePassword123!",
    "phone": "+1234567890",
    "country": "United States",
    "country_code": "+1"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Registration successful. Please verify your email with the OTP sent."
}
```

<Info>
  An OTP (One-Time Password) will be sent to your email. You must verify within 10 minutes.
</Info>

### Verify Your Email

Enter the 6-digit OTP received via email:

```bash theme={null}
curl -X POST https://api.fincept.in/user/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "otp": "123456"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "api_key": "fk_user_abc123xyz789...",
    "message": "Account verified successfully"
  }
}
```

**Important:** Save your API key securely - it will only be shown once!

### Login to Existing Account

Retrieve your API key if you already have an account:

```bash theme={null}
curl -X POST https://api.fincept.in/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "SecurePassword123!"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "api_key": "fk_user_abc123xyz789...",
    "message": "Login successful"
  }
}
```

<Warning>
  After 5 failed login attempts, your account will be locked for 30 minutes for security.
</Warning>

### Create Guest Account

Get a temporary key for testing (no email required):

```bash theme={null}
curl -X POST https://api.fincept.in/guest/create \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "unique-device-identifier",
    "device_name": "MacBook Pro",
    "platform": "macos"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "api_key": "fk_guest_temp123...",
    "credit_balance": 50,
    "expires_at": "2024-01-16T10:30:00Z",
    "requests_today": 0
  }
}
```

## Using Your API Key

Include your API key in the `X-API-Key` header for all requests:

```bash theme={null}
curl https://api.fincept.in/quantlib/pricing/black-scholes \
  -H "X-API-Key: fk_user_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"spot": 100, "strike": 105, ...}'
```

### Environment Variables (Recommended)

Store your API key in an environment variable:

```bash theme={null}
# Linux/Mac
export FINCEPT_API_KEY="fk_user_your_key_here"

# Windows (CMD)
set FINCEPT_API_KEY=fk_user_your_key_here

# Windows (PowerShell)
$env:FINCEPT_API_KEY="fk_user_your_key_here"
```

Then use it in requests:

```bash theme={null}
curl https://api.fincept.in/user/profile \
  -H "X-API-Key: $FINCEPT_API_KEY"
```

## API Key Management

### View Your Profile

Check your account details and credit balance:

```bash theme={null}
curl https://api.fincept.in/user/profile \
  -H "X-API-Key: fk_user_your_key_here"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "id": 42,
    "username": "johndoe",
    "email": "john@example.com",
    "account_type": "free",
    "credit_balance": 350,
    "is_verified": true,
    "is_admin": false,
    "mfa_enabled": false,
    "created_at": "2024-01-15T10:30:00Z",
    "last_login_at": "2024-01-16T08:15:00Z"
  }
}
```

### Regenerate API Key

If your key is compromised, regenerate it immediately:

```bash theme={null}
curl -X POST https://api.fincept.in/user/regenerate-api-key \
  -H "X-API-Key: fk_user_old_key_here"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "api_key": "fk_user_new_key_here...",
    "message": "API key regenerated successfully"
  }
}
```

<Warning>
  Your old API key will stop working immediately. Update all applications using the old key.
</Warning>

### View Login History

Monitor recent login activity for security:

```bash theme={null}
curl https://api.fincept.in/user/login-history?limit=10 \
  -H "X-API-Key: fk_user_your_key_here"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "login_history": [
      {
        "id": 123,
        "ip_address": "203.0.113.45",
        "user_agent": "curl/7.68.0",
        "login_successful": true,
        "created_at": "2024-01-16T08:15:00Z"
      }
    ],
    "total": 15,
    "successful_logins": 14,
    "failed_logins": 1
  }
}
```

## Multi-Factor Authentication (MFA)

Add an extra layer of security with email-based MFA.

### Enable MFA

```bash theme={null}
curl -X POST https://api.fincept.in/user/mfa/enable \
  -H "X-API-Key: fk_user_your_key_here"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "message": "MFA enabled successfully. You will receive a verification code via email on your next login."
  }
}
```

### Login with MFA

When MFA is enabled, logging in is a two-step process:

**Step 1: Login with credentials**

```bash theme={null}
curl -X POST https://api.fincept.in/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "SecurePassword123!"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "mfa_required": true,
    "message": "MFA code sent to your email. Please verify to complete login."
  }
}
```

**Step 2: Verify MFA code**

```bash theme={null}
curl -X POST https://api.fincept.in/user/verify-mfa \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "otp": "654321"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "api_key": "fk_user_your_key_here",
    "message": "MFA verification successful. Login complete."
  }
}
```

### Disable MFA

Requires password confirmation:

```bash theme={null}
curl -X POST https://api.fincept.in/user/mfa/disable \
  -H "X-API-Key: fk_user_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "SecurePassword123!"
  }'
```

## Password Management

### Reset Password

If you forgot your password:

**Step 1: Request reset code**

```bash theme={null}
curl -X POST https://api.fincept.in/user/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com"
  }'
```

**Step 2: Reset with OTP**

```bash theme={null}
curl -X POST https://api.fincept.in/user/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "otp": "123456",
    "new_password": "NewSecurePassword456!"
  }'
```

## Security Best Practices

### Protect Your API Key

<AccordionGroup>
  <Accordion title="Never commit keys to version control">
    Add your API key to `.gitignore` and use environment variables instead.

    ```bash theme={null}
    # .gitignore
    .env
    config.json
    secrets.*
    ```
  </Accordion>

  <Accordion title="Use environment variables">
    Store API keys in environment variables, not in code.

    ```python theme={null}
    import os
    API_KEY = os.environ.get('FINCEPT_API_KEY')
    ```
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Regenerate API keys periodically (every 90 days recommended).
  </Accordion>

  <Accordion title="Use separate keys per environment">
    Create different accounts for development, staging, and production.
  </Accordion>

  <Accordion title="Monitor login activity">
    Regularly check your login history for suspicious activity.
  </Accordion>

  <Accordion title="Enable MFA">
    Add multi-factor authentication for sensitive accounts.
  </Accordion>
</AccordionGroup>

### Rate Limits

Prevent abuse and ensure fair usage:

**Registered Users:**

* Free tier: 500 requests/hour
* Basic tier: 1,000 requests/hour
* Standard tier: 2,000 requests/hour
* Pro tier: 5,000 requests/hour
* Enterprise tier: Custom limits

**Guest Users:**

* 50 requests/day
* 60 requests/hour

Rate limit headers in responses:

```bash theme={null}
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1640995200
```

## Error Responses

### Invalid API Key

```json theme={null}
{
  "success": false,
  "message": "Invalid or expired API key",
  "detail": "Valid API key required"
}
```

**HTTP Status:** 401 Unauthorized

### Expired Guest Key

```json theme={null}
{
  "success": false,
  "message": "Guest API key has expired",
  "detail": "Valid guest API key required or session expired"
}
```

**HTTP Status:** 401 Unauthorized

### Rate Limit Exceeded

```json theme={null}
{
  "success": false,
  "message": "Rate limit exceeded",
  "detail": "Too many requests. Please try again later."
}
```

**HTTP Status:** 429 Too Many Requests

Includes `Retry-After` header with seconds until reset.

### Account Locked

```json theme={null}
{
  "success": false,
  "message": "Account temporarily locked due to failed attempts",
  "detail": "Please try again after 30 minutes or reset your password."
}
```

**HTTP Status:** 423 Locked

## Code Examples

### Python with requests

```python theme={null}
import os
import requests

API_KEY = os.environ.get('FINCEPT_API_KEY')
BASE_URL = "https://api.fincept.in"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Check profile
response = requests.get(f"{BASE_URL}/user/profile", headers=headers)
profile = response.json()
print(f"Credits: {profile['data']['credit_balance']}")
```

### JavaScript with fetch

```javascript theme={null}
const API_KEY = process.env.FINCEPT_API_KEY;
const BASE_URL = "https://api.fincept.in";

async function getProfile() {
  const response = await fetch(`${BASE_URL}/user/profile`, {
    headers: {
      "X-API-Key": API_KEY
    }
  });

  const data = await response.json();
  console.log("Credits:", data.data.credit_balance);
}
```

### cURL with environment variable

```bash theme={null}
export FINCEPT_API_KEY="fk_user_your_key_here"

curl https://api.fincept.in/user/profile \
  -H "X-API-Key: $FINCEPT_API_KEY"
```

## FAQs

<AccordionGroup>
  <Accordion title="How do I get an API key?">
    Register at `/user/register`, verify your email with the OTP, and you'll receive your permanent API key.
  </Accordion>

  <Accordion title="Can I have multiple API keys?">
    No, each account has one API key. Create multiple accounts if you need separate keys for different environments.
  </Accordion>

  <Accordion title="What happens if I lose my API key?">
    Login to your account at `/user/login` to retrieve your existing API key.
  </Accordion>

  <Accordion title="Can I change my API key?">
    Yes, use the `/user/regenerate-api-key` endpoint to generate a new key. Your old key will stop working immediately.
  </Accordion>

  <Accordion title="Do guest keys support all endpoints?">
    Guest keys only have access to Free tier endpoints. Upgrade to a registered account for full access.
  </Accordion>

  <Accordion title="How long do API keys last?">
    Registered user keys never expire. Guest keys expire after 24 hours.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Pricing Guide" icon="credit-card" href="/pricing">
    Learn about credit costs and subscription plans
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first API call in 5 minutes
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Browse complete endpoint documentation
  </Card>

  <Card title="QuantLib Overview" icon="chart-line" href="/quantlib-overview">
    Explore all modules and capabilities
  </Card>
</CardGroup>

Need help? Contact us at **[support@fincept.in](mailto:support@fincept.in)** or join our Discord community.