Skip to main content
---
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
API keys start with nb_ and are 48 characters long. Generate them in your dashboard under Profile → API Keys.

​
Getting Your API Key

  1. Log in to 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
API access requires a VIP or Elite subscription. If you’re on a lower plan, upgrade at elumenta.ru/web/billing.

​
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

POST /api/v2/auth/telegram
Content-Type: application/json

{
  "id": 123456789,
  "first_name": "Ivan",
  "username": "ivan_dev",
  "auth_date": 1709900000,
  "hash": "abc123..."
}
Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 900,
  "user": {
    "id": 42,
    "name": "Ivan",
    "plan": "vip",
    "token_balance": 1500
  }
}

​
Email / Password

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): 
POST /api/v2/auth/login-phone
Content-Type: application/json

{
  "phone": "+79991234567",
  "password": "your_password"
}
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.

​
Google OAuth

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: 
POST /api/v2/auth/refresh

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "expires_in": 900
}

​
Security Best Practices

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.
Store your API key in environment variables, never hardcode it:
# .env
ELUMENTA_API_KEY=nb_your_key_here

import os
api_key = os.environ["ELUMENTA_API_KEY"]
You can generate multiple keys and delete old ones. Each key appears as a separate entry in your dashboard with its last-used timestamp.
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).

​
Error Responses

HTTP CodeErrorMeaning
401Not authenticatedMissing or malformed Authorization header
401Invalid or expired tokenToken is wrong or has expired
403Insufficient planAPI access requires VIP or Elite plan
429Rate limit exceededToo many requests, see Rate Limits