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

# Authentication

````mdx theme={null}
---
title: "Authentication"
description: "All API requests require a Bearer token in the Authorization header"
---

## API Key Authentication

All Elumenta API requests must include your API key as a Bearer token:

```http
Authorization: Bearer nb_YOUR_API_KEY
````

<Note>
  API keys start with `nb_` and are 48 characters long. Generate them in your dashboard under **Profile → API Keys**.
</Note>

## Getting Your API Key

1. Log in to [elumenta.ru/web](https://elumenta.ru/web)
2. Go to **Profile → API Keys**
3. Click **+ Generate New Key**
4. Give it a name (e.g. `my-app-production`)
5. Copy and save the key immediately — it won't be shown again

<Warning>
  API access requires a **VIP** or **Elite** subscription. If you're on a lower plan, upgrade at [elumenta.ru/web/billing](https://elumenta.ru/web/billing).
</Warning>

## Web Auth (for building user-facing apps)

If you're building an application where end-users authenticate with their Elumenta account, use the standard web auth flow instead of API keys.

### Telegram Login

```http theme={null}
POST /api/v2/auth/telegram
Content-Type: application/json

{
  "id": 123456789,
  "first_name": "Ivan",
  "username": "ivan_dev",
  "auth_date": 1709900000,
  "hash": "abc123..."
}
```

Response:

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 900,
  "user": {
    "id": 42,
    "name": "Ivan",
    "plan": "vip",
    "token_balance": 1500
  }
}
```

### Email / Password

```http theme={null}
POST /api/v2/auth/login
Content-Type: application/json

{
  "email": "ivan@example.com",
  "password": "your_password"
}
```

### Phone / Password

For users registered via SMS (Russian phone numbers):

```http theme={null}
POST /api/v2/auth/login-phone
Content-Type: application/json

{
  "phone": "+79991234567",
  "password": "your_password"
}
```

<Note>
  Phone numbers must be in E.164 format (`+7XXXXXXXXXX` for Russian numbers). The web interface auto-detects whether you're entering an email or phone and routes to the appropriate endpoint.
</Note>

### Google OAuth

```http theme={null}
POST /api/v2/auth/google
Content-Type: application/json

{
  "code": "4/0AX4XfWh...",
  "redirect_uri": "https://yourapp.com/auth/google/callback"
}
```

## Token Refresh

Access tokens expire after **15 minutes**. Use the refresh token (stored as an httpOnly cookie) to get a new one:

```http theme={null}
POST /api/v2/auth/refresh
```

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "expires_in": 900
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Never expose keys in client-side code">
    API keys should only be used server-side. If you need to call the API from a browser or mobile app, build a proxy endpoint on your server that adds the key before forwarding the request.
  </Accordion>

  <Accordion title="Use environment variables">
    Store your API key in environment variables, never hardcode it:

    ```bash theme={null}
    # .env
    ELUMENTA_API_KEY=nb_your_key_here
    ```

    ```python theme={null}
    import os
    api_key = os.environ["ELUMENTA_API_KEY"]
    ```
  </Accordion>

  <Accordion title="Rotate keys regularly">
    You can generate multiple keys and delete old ones. Each key appears as a separate entry in your dashboard with its last-used timestamp.
  </Accordion>

  <Accordion title="Rate limits apply per key">
    Each API key shares the rate limits of your subscription plan. If you're building a multi-tenant app, consider one key per customer (contact support for high-volume arrangements).
  </Accordion>
</AccordionGroup>

## Error Responses

| HTTP Code | Error                      | Meaning                                                        |
| --------- | -------------------------- | -------------------------------------------------------------- |
| `401`     | `Not authenticated`        | Missing or malformed Authorization header                      |
| `401`     | `Invalid or expired token` | Token is wrong or has expired                                  |
| `403`     | `Insufficient plan`        | API access requires VIP or Elite plan                          |
| `429`     | `Rate limit exceeded`      | Too many requests, see [Rate Limits](/en/concepts/rate-limits) |

```
```