API v1

TeleAuth documentation

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

Getting started

Introduction

TeleAuth is a Telegram authentication and verification platform for developers. You create a project, connect your own Telegram bot, generate an API key, and call the API from your backend. TeleAuth never forwards Telegram login codes — it only uses official Telegram mechanisms.

Quick start

Four steps: create a project, connect your BotFather token in the dashboard, generate an API key, then send and verify a code from your server.

curl

# 1. send a code to a Telegram user
curl -X POST https://teleauth.run.place/api/public/v1/otp/send \
  -H "x-api-key: $TELEAUTH_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "username": "@ada_lovelace" }'

# 2. verify what the user typed
curl -X POST https://teleauth.run.place/api/public/v1/otp/verify \
  -H "x-api-key: $TELEAUTH_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "username": "@ada_lovelace", "code": "123456" }'

Authentication

Every API request is authenticated with a project API key sent in the x-api-key header. Keys are scoped to a single project and environment and must only be used from server-side code.

header

x-api-key: ta_live_your_api_key

OTP

POST /v1/otp/send

Sends a six-digit code through your connected bot. Provide a Telegram username. The user must have pressed Start on your bot at least once.

request / response

POST /api/public/v1/otp/send
{ "username": "ada_lovelace" }

200 OK
{
  "ok": true,
  "sent": true,
  "channel": "username",
  "expires_in": 300
}

POST /v1/otp/verify

Checks a code against the stored hash for that recipient. Codes expire after 5 minutes and allow 5 attempts. A successful verification consumes the code.

request / response

POST /api/public/v1/otp/verify
{ "username": "@ada_lovelace", "code": "123456" }

200 OK
{ "ok": true, "verified": true }

400 Bad Request
{ "ok": false, "error": "invalid_code", "attempts_left": 4 }

Delivery requirements

Telegram bots can only message users who have started a conversation with them. The user must press Start on your bot once. No phone number or contact sharing is required.

Telegram verification

POST /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.

request / response

POST /api/public/v1/verify
{ "type": "initData", "initData": "<Telegram.WebApp.initData>" }

200 OK
{
  "verified": true,
  "user": { "id": "123456789", "username": "ada", "first_name": "Ada" },
  "auth_date": 1755720000,
  "environment": "production"
}

Authentication flow

Your browser never talks to TeleAuth directly. The user authorizes inside Telegram, your server forwards the signed payload, and TeleAuth verifies it before reporting a verified identity.

flow

Browser -> your server -> TeleAuth
TeleAuth -> Telegram signature check (server-side)
TeleAuth -> your webhook (verified identity)

Platform

Projects

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

API keys

Keys stay visible in your project settings, so you can reveal and copy them whenever you need. Only the project owner can read them. Revoke a key at any time — revocation takes effect immediately.

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 signature

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 });
}

Authentication logs

Every send, verify, success and failure is recorded with recipient, status and timestamp, viewable per project in the dashboard.

Reference

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

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

Security

Use HTTPS everywhere, keep API keys, bot tokens 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.

Endpoint index

Endpoints available in the current API version.

endpoints

POST /api/public/v1/otp/send     # send a code over Telegram
POST /api/public/v1/otp/verify   # verify a code
POST /api/public/v1/verify       # verify initData / Login Widget payload