TeleAuth documentation

Everything needed to integrate Telegram authentication, from your first request to production webhooks.

Introduction

TeleAuth is a Telegram authentication and verification platform for developers. You create a project, generate API credentials, call the API from your backend, and receive verified results through signed webhooks.

Quick Start

Create a project, connect your Telegram bot token, generate an API key, then verify a Telegram Login Widget or Mini App payload from your server.

curl

curl -X POST https://teleauth.app/api/public/v1/verify \
  -H "Authorization: Bearer ta_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"type":"initData","initData":"<Telegram.WebApp.initData>"}'

Verify Endpoint

POST /api/public/v1/verify accepts either a Mini App initData string or a Login Widget payload. The signature is checked against your project's bot token, payloads older than 5 minutes are rejected, and every attempt is written to your authentication logs.

response

{
  "verified": true,
  "user": { "id": "123456789", "username": "naqeeb", "first_name": "Naqeeb" },
  "auth_date": 1755720000,
  "environment": "production"
}

Authentication

Every API request is authenticated with a bearer API key. Keys are scoped to a single project and environment, and must only be used from server-side code.

header

Authorization: Bearer ta_live_your_api_key

Projects

A project represents one application and environment. Create separate development and production projects so credentials, webhooks and logs stay isolated.

API Keys

Keys are shown once at creation and stored only as a prefix plus a hash. If a key is lost, revoke it and create a new one. Revocation takes effect immediately.

Telegram Authentication

TeleAuth uses official Telegram authentication. Your user is sent to a Telegram authorization step, consents, and TeleAuth verifies the signed result server-side before reporting a verified identity to your application.

flow

Your app -> TeleAuth -> Telegram authorization
Telegram -> TeleAuth (signature verified server-side)
TeleAuth -> your webhook (verified identity)

Webhooks

Register an endpoint per project and verify the HMAC signature header before processing an event. Failed deliveries are recorded and can be retried from the dashboard.

verify

const expected = crypto
  .createHmac("sha256", process.env.TELEAUTH_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

if (`sha256=${expected}` !== request.headers["x-teleauth-signature"]) {
  return new Response("Invalid signature", { status: 401 });
}

Errors

Errors use standard HTTP status codes with a machine-readable code and a human-readable message. Raw internal errors are never returned.

error

401 Unauthorized

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or revoked."
  }
}

Security

Use HTTPS for all endpoints, keep API keys and webhook secrets server-side, rotate credentials regularly, and verify every webhook signature. Never place a TeleAuth secret in browser JavaScript.

Rate Limits

Rate limits are applied per API key. When exceeded, the API returns 429 with a code of rate_limit_exceeded; retry after the interval indicated in the response headers.

API Reference

Endpoints available in the current API version.

endpoints

POST /api/public/v1/verify   # verify initData or Login Widget payload

# managed from the dashboard
projects, API keys, webhooks, authentication logs