POST /v1/link-token

Purpose

Create a one-time link token for your app user and receive Telegram deep-link metadata.

Auth requirement

Bearer API key (Authorization: Bearer <key>).

Request schema

{
  "user_id": "string"
}

Response schema

201 Created

{
  "token": "string",
  "expires_at": "ISO-8601",
  "deep_link": "https://t.me/<bot>?start=<token>"
}

Error cases

• 401 unauthorized: invalid/inactive API key.
• 400 invalid_request: malformed JSON or invalid user_id.

Curl example

curl -X POST "$GATEWAY_BASE_URL/v1/link-token" \
  -H "Authorization: Bearer $ETN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"user_123"}'

Notes and limits

• Token TTL is 15 minutes.
• Token is single-use.
• Token records snapshot the branding label (API key label first, developer name fallback).