Backend
Authentication

Authentication

The IBW Backend Service supports multiple authentication methods depending on the endpoint and user type.

Authentication Methods

1. Telegram Authentication

Used for user-facing endpoints. Users authenticate via Telegram bot tokens.

Header:

X-Telegram-Auth: <telegram_bot_token>

How it works:

  1. User authenticates with Telegram bot
  2. Telegram provides authentication data
  3. Client sends X-Telegram-Auth header with Telegram auth data
  4. Server validates the Telegram authentication
  5. Server extracts user information from Telegram data

Middleware: TelegramAuthMiddlewareFunc

Usage:

app.Get("/api/v1/users/me", 
    middleware.TelegramAuthMiddlewareFunc(cfg), 
    handler.GetMe)

2. Optional Telegram Authentication

Some endpoints support optional authentication for personalized data.

Middleware: OptionalTelegramAuthMiddlewareFunc

Behavior:

  • If auth header is present, user is authenticated
  • If auth header is missing, request proceeds without user context
  • Response may vary based on authentication status

Usage:

app.Get("/api/v1/users", 
    middleware.OptionalTelegramAuthMiddlewareFunc(cfg), 
    handler.ListUsers)

3. JWT Authentication

Used for API access tokens.

Header:

Authorization: Bearer <jwt_token>

Token Generation:

  • Tokens are generated via /api/v1/auth/login
  • Tokens contain user information
  • Tokens have expiration time

Middleware: JWT validation in handlers

4. Admin API Key Authentication

Used for admin endpoints.

Header:

X-API-Key: <admin_api_key>

Configuration:

  • Set ADMIN_API_KEY in environment variables
  • Admin API key is validated on each admin request

Middleware: AdminAPIKeyAuth

Usage:

admin := v1.Group("/admin", middleware.AdminAPIKeyAuth(cfg))

5. Admin JWT Authentication

Alternative admin authentication using JWT tokens.

Header:

Authorization: Bearer <admin_jwt_token>

Middleware: AdminAuthMiddleware

Usage:

admin := v1.Group("/admin", middleware.AdminAuthMiddleware(cfg, jwtService))

Authentication Flow

User Authentication Flow

  1. User interacts with Telegram bot
  2. Bot provides authentication data
  3. Client includes auth data in X-Telegram-Auth header
  4. Server validates Telegram auth data
  5. Server extracts telegram_id from auth data
  6. Server looks up or creates user in database
  7. User context is attached to request

Admin Authentication Flow

  1. Admin provides API key or JWT token
  2. Server validates credentials
  3. Admin context is attached to request
  4. Admin endpoints become accessible

Protected Endpoints

User Protected Endpoints

Require Telegram authentication:

  • /api/v1/users/me - Get current user
  • /api/v1/users/socials - Update socials
  • /api/v1/events/attend - Register for event
  • /api/v1/quests/:id/start - Start quest
  • /api/v1/connections/* - Connection management
  • /api/v1/notifications/* - Notifications

Admin Protected Endpoints

Require admin authentication:

  • /api/v1/admin/* - All admin endpoints

Public Endpoints

No authentication required:

  • /healthz - Health check
  • /api/v1/events - List events (public data)
  • /api/v1/conferences - List conferences
  • /api/v1/speakers - List speakers
  • /api/v1/quests - List quests (public data)
  • /api/v1/feedback - Submit feedback

Error Responses

Unauthorized (401)

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

Forbidden (403)

{
  "error": "Forbidden",
  "code": "FORBIDDEN"
}

Invalid Token (401)

{
  "error": "Invalid token",
  "code": "INVALID_TOKEN"
}

Security Best Practices

  1. Always use HTTPS in production
  2. Validate tokens on every request
  3. Set token expiration times
  4. Rotate API keys regularly
  5. Use secure storage for credentials
  6. Implement rate limiting on auth endpoints
  7. Log authentication failures for security monitoring
  8. Never expose API keys or tokens in client code

Token Management

JWT Token Structure

{
  "user_id": 123,
  "telegram_id": 456789,
  "exp": 1234567890,
  "iat": 1234567890
}

Token Expiration

  • Tokens have expiration times
  • Expired tokens return 401 Unauthorized
  • Clients should refresh tokens before expiration

Rate Limiting

Authentication endpoints are rate-limited to prevent abuse:

  • Login attempts: Limited per IP
  • API key validation: Limited per key
  • Telegram auth: Limited per user

Testing Authentication

Test Telegram Auth

curl -X GET http://localhost:8080/api/v1/users/me \
  -H "X-Telegram-Auth: <telegram_auth_data>"

Test Admin API Key

curl -X GET http://localhost:8080/api/v1/admin/users \
  -H "X-API-Key: <admin_api_key>"

Test JWT Token

curl -X GET http://localhost:8080/api/v1/users/me \
  -H "Authorization: Bearer <jwt_token>"
Setup & ConfigurationMiddleware