Telegram Authentication

This section covers Telegram-based authentication operations available in the GraphQL Main API.

Important Note: Telegram sign-up functionality has been deprecated. New users cannot register using Telegram. Existing users who previously signed up with Telegram can still sign in, but they will be prompted to upgrade their authentication method to email, Google, or Meta.

Deprecated Sign-in Method

Telegram authentication is now considered a deprecated sign-in method. The following rules apply:

• New user registration via Telegram is no longer supported
• Existing users can still sign in using Telegram as an initial step
• After signing in with Telegram, users will be prompted to connect their account to Google, Meta, or provide an email
• Once a user has associated their account with email, Google, or Meta, they can no longer use Telegram to sign in
• The system will mark Telegram as a deprecated sign-in method after the user upgrades to a new authentication method

Mutations

authWithTelegramMiniApp

Authenticate a user through the Telegram Mini App.

mutation AuthWithTelegramMiniApp($input: AuthWithTelegramMiniAppInput!) {
  authWithTelegramMiniApp(input: $input) {
    status
    accessToken
    refreshToken
    expiresIn
    user {
      id
      username
      email
      # other user fields
    }
    errorMessage
  }
}

Input:

input AuthWithTelegramMiniAppInput {
  hash: String!           // Hash value provided by Telegram for verification
  authDate: String!       // Date of authentication from Telegram
  queryId: String         // Query ID from the Telegram Mini App
  signature: String!      // Signature from Telegram
  user: String!          // User data from Telegram in JSON format
  fingerprint: String!    // Device fingerprint for additional security
}

Returns:

type LoginResponse {
  status: ResponseStatus!        // Will be ERROR for now
  user: UserModel                // The authenticated user's details (null for now)
  errorMessage: String           // Will be "NOT_IMPLEMENTED"
  onBoardingCompleted: Boolean   // Whether the user has completed onboarding (null for now)
  newUser: Boolean               // Whether this is a new user (null for now)
  mfaPhoneHint: String           // If MFA is enabled, a hint about the phone number (null for now)
  mfaType: MfaType               // Type of MFA if required for login (null for now)
  unlocksAt: Date                // When user is no longer restricted from making this request (null for now)
}

Note: Upon successful authentication, the accessToken and refreshToken would be set as HTTP cookies and not directly returned in the response body.

Current Response:

{
  "data": {
    "authWithTelegramMiniApp": {
      "status": "ERROR",
      "errorMessage": "NOT_IMPLEMENTED",
      "user": null,
      "onBoardingCompleted": null,
      "newUser": null,
      "mfaPhoneHint": null,
      "mfaType": null,
      "unlocksAt": null
    }
  }
}

registerWithTelegram

Register a new user account using Telegram authentication.

mutation RegisterWithTelegram($input: AuthWithTelegramInput!) {
  registerWithTelegram(input: $input) {
    status
    user {
      id
      username
      email
      # other user fields
    }
    errorMessage
    onBoardingCompleted
    newUser
    mfaPhoneHint
    mfaType
    unlocksAt
  }
}

Input:

input AuthWithTelegramInput {
  hash: String!                   // Hash value provided by Telegram for verification
  id: Int!                        // Telegram user ID
  authDate: Int!                  // Date of authentication in Unix timestamp format
  firstName: String               // User's first name from Telegram
  lastName: String                // User's last name from Telegram
  username: String                // Telegram username
  photoUrl: String                // URL to the user's Telegram profile photo
  fingerprint: String!            // Device fingerprint for additional security
  agreedToTerms: Boolean!         // Confirmation that user has agreed to terms of service
  receiveMarketingOffers: Boolean! // User's preference for marketing communications
  referrerUserId: String          // Optional referrer user ID
  referrerUsername: String        // Optional referrer username
  promoCode: String               // Optional promotion code
}

Returns:

type LoginResponse {
  status: ResponseStatus!        // Will be ERROR for now
  user: UserModel                // The authenticated user's details (null for now)
  errorMessage: String           // Will be "NOT_IMPLEMENTED"
  onBoardingCompleted: Boolean   // Whether the user has completed onboarding (null for now)
  newUser: Boolean               // Whether this is a new user (null for now)
  mfaPhoneHint: String           // If MFA is enabled, a hint about the phone number (null for now)
  mfaType: MfaType               // Type of MFA if required for login (null for now)
  unlocksAt: Date                // When user is no longer restricted from making this request (null for now)
}

Current Response:

{
  "data": {
    "registerWithTelegram": {
      "status": "ERROR",
      "errorMessage": "NOT_IMPLEMENTED",
      "user": null,
      "onBoardingCompleted": null,
      "newUser": null,
      "mfaPhoneHint": null,
      "mfaType": null,
      "unlocksAt": null
    }
  }
}

loginWithTelegram

Log in an existing user with Telegram authentication.

mutation LoginWithTelegram($input: AuthWithTelegramInput!) {
  loginWithTelegram(input: $input) {
    status
    user {
      id
      username
      email
      # other user fields
    }
    errorMessage
    onBoardingCompleted
    newUser
    mfaPhoneHint
    mfaType
    unlocksAt
  }
}

Input:

input AuthWithTelegramInput {
  hash: String!                   // Hash value provided by Telegram for verification
  id: Int!                        // Telegram user ID
  authDate: Int!                  // Date of authentication in Unix timestamp format
  firstName: String               // User's first name from Telegram
  lastName: String                // User's last name from Telegram
  username: String                // Telegram username
  photoUrl: String                // URL to the user's Telegram profile photo
  fingerprint: String!            // Device fingerprint for additional security
  agreedToTerms: Boolean          // Optional for login (required for registration)
  receiveMarketingOffers: Boolean // Optional for login (required for registration)
}

Returns:

type LoginResponse {
  status: ResponseStatus!        // Will be ERROR for now
  user: UserModel                // The authenticated user's details (null for now)
  errorMessage: String           // Will be "NOT_IMPLEMENTED"
  onBoardingCompleted: Boolean   // Whether the user has completed onboarding (null for now)
  newUser: Boolean               // Whether this is a new user (null for now)
  mfaPhoneHint: String           // If MFA is enabled, a hint about the phone number (null for now)
  mfaType: MfaType               // Type of MFA if required for login (null for now)
  unlocksAt: Date                // When user is no longer restricted from making this request (null for now)
}

Current Response:

{
  "data": {
    "loginWithTelegram": {
      "status": "ERROR",
      "errorMessage": "NOT_IMPLEMENTED",
      "user": null,
      "onBoardingCompleted": null,
      "newUser": null,
      "mfaPhoneHint": null,
      "mfaType": null,
      "unlocksAt": null
    }
  }
}

linkTelegram

Link a Telegram account to an existing user account.

mutation LinkTelegram($input: LinkTelegramInput!) {
  linkTelegram(input: $input) {
    status
    errorMessage
  }
}

Input:

input LinkTelegramInput {
  hash: String!           // Hash value provided by Telegram for verification
  id: Int!                // Telegram user ID
  authDate: Int!          // Date of authentication in Unix timestamp format
  firstName: String       // User's first name from Telegram
  lastName: String        // User's last name from Telegram
  username: String        // Telegram username
  photoUrl: String        // URL to the user's Telegram profile photo
}

Returns:

type StatusHandlerResponse {
  status: ResponseStatus!   // Will be ERROR for now
  errorMessage: String      // Will be "NOT_IMPLEMENTED"
}

Current Response:

{
  "data": {
    "linkTelegram": {
      "status": "ERROR",
      "errorMessage": "NOT_IMPLEMENTED"
    }
  }
}

Future Security Considerations

When the Telegram authentication is implemented in the future, the following security measures would be in place:

1. Data Validation: The server will verify the authenticity of the Telegram data using the hash and secret key.
2. Timestamp Verification: The authDate will be checked to ensure the authentication request is recent.
3. Fingerprinting: Device fingerprinting will be used as an additional security measure.
4. Lockout Protection: Redis-based locks will prevent brute force attacks.

Technical Implementation Details

When implemented, Telegram authentication will rely on the data provided by Telegram when a user authorizes the application:

1. Telegram sends a data string that includes user details and a hash
2. The server verifies the hash using the Bot Token as a secret key
3. If verification is successful, the user is authenticated

For Mini App authentication, the process is similar but uses the data provided by the Telegram Mini App platform.