---
title: "Authentication"
description: "Auth.js v5 session endpoints, providers (Telegram OIDC + Mini App initData), and role hierarchy for Ring Platform"
locale: "en"
---
# Authentication API

> **Info**
> Use **Founder** / **Developer** tabs in the docs sidebar to filter this page.

Ring uses **Auth.js v5** for sessions and multi-provider sign-in. Product overview: [Authentication](/docs/features/authentication.md). Architecture: [Authentication Architecture](/docs/architecture/authentication.md).

## Supported providers (shipped)

| Provider | Notes |
|----------|--------|
| Google | OAuth redirect + One Tap |
| Telegram (web) | OIDC via `oauth.telegram.org` when `AUTH_TELEGRAM_*` set |
| Telegram Mini App | Credentials `telegram-miniapp` — WebAppData HMAC on `initData` |
| Apple | Sign in with Apple |
| Ring Mailer | OTP / magic link / password Credentials |
| Crypto wallet | Nonce + signature Credentials |

```mermaid
sequenceDiagram
    participant User
    participant UI as Login UI
    participant Auth as Auth.js
    participant IdP as Google / Telegram / Apple
    participant DB as Adapter DB

    User->>UI: Sign in
    UI->>Auth: signIn(provider)
    Auth->>IdP: OAuth / OIDC redirect
    IdP->>Auth: Authorization code
    Auth->>DB: Resolve / link user + accounts
    Auth->>UI: JWT session cookie
    UI->>User: Authenticated
```

### For founders

## What this API means for operators

- Members authenticate through the login UI; you configure provider secrets, not custom REST “login” payloads.
- Session cookies are **httpOnly**; browsers never hold the Auth.js `AUTH_SECRET`.
- Telegram Login needs BotFather **Web Login** Allowed URLs — see the checklist on [Authentication](/docs/features/authentication.md).
- Mini App auth needs a bot API token (`TELEGRAM_MINI_APP_BOT_TOKEN` preferred); there is no stock platform Mini App shell page.
- Admin Telegram chat control is a **different** surface: [Manage via Telegram](/docs/features/manage-via-telegram.md).

### For developers

## Auth.js endpoints

Handlers: `app/api/auth/[...nextauth]/route.ts`.

| Method / path | Role |
|---------------|------|
| Auth.js sign-in / callback / CSRF | Provider redirects and token exchange |
| `GET /api/auth/session` | Current session JSON for `useSession` / client |
| `POST /api/auth/signout` | Invalidate session cookie |
| `GET /api/auth/callback/telegram` | Telegram OIDC callback (Auth.js) |
| `GET /api/auth/telegram/callback` | **Profile linking** Login Widget (requires session) |

### Server-side gate

{`import { auth } from '@/auth'

export default async function ProtectedPage() {
  const session = await auth()
  if (!session) return Please sign in
  return Welcome, {session.user.name}!
}`}

### Client-side session

{`import { useSession } from 'next-auth/react'

export default function UserProfile() {
  const { data: session, status } = useSession()
  if (status === 'loading') return Loading...
  if (!session) return Not authenticated
  return Hello, {session.user.name}!
}`}

### Telegram client triggers

{`import { signIn } from 'next-auth/react'
// Web OIDC (browser):
await signIn('telegram', { callbackUrl })
// Mini App (inside Telegram WebApp):
await signIn('telegram-miniapp', { initData, redirect: false })`}

Prefer `features/auth/components/telegram-signin-button.tsx` for locale-safe OIDC callbacks.

### Role hierarchy

Canonical labels live in `features/auth/user-role.ts` (visitor → subscriber → member → confidential → admin → superadmin). Prefer `useAuth()` / `hasRole` helpers over hard-coding string compares in UI.

### Security notes

- JWT session strategy; `__Secure-` cookie prefix in production
- CSRF protection via Auth.js
- Telegram OIDC: PKCE + state; widget linking: `SHA256(bot_token)` HMAC; Mini App: **WebAppData** HMAC — never mix the three
- Do not log bot tokens, client secrets, raw `id_token`s, or raw `initData`

## Related documentation

  
- [features/authentication](/docs/features/authentication.md) — Prerequisite: which providers ship and how Telegram Login + Mini App are enabled.

  
- [architecture/authentication](/docs/architecture/authentication.md) — Deep-dive: adapters, OIDC + Mini App modules, and env wiring.

  
- [examples/authentication](/docs/examples/authentication.md) — Next-step: code samples for signIn and SessionProvider.

  
- [features/subscriptions](/docs/features/subscriptions.md) — See-also: telegram_stars membership invoices share the Mini App bot token.

  
- [features/manage-via-telegram](/docs/features/manage-via-telegram.md) — See-also: admin bot — not member OIDC or Mini App Credentials.

  
- [api/admin](/docs/api/admin.md) — See-also: admin HTTP surfaces after session + role checks.