Secure Storage

SecureStorage provides encrypted local secure storage for sensitive data such as authentication tokens and keys. Data is encrypted before being stored on the device. Accessed via Telegram.WebApp.SecureStorage. Bot API 8.0+

Limits

Item	Limit
Maximum number of entries	10
Maximum key length	128 characters
Maximum value length	2048 characters
Key characters	A-Z, a-z, 0-9, _, -

Methods

setItem

Telegram.WebApp.SecureStorage.setItem(key, value, callback)

Securely stores a key-value pair.

Parameter	Type	Required	Description
key	String	Yes	Key name, 1-128 characters
value	String	Yes	Value, 0-2048 characters
callback	Function	No	Callback with (error, success) parameters

Telegram.WebApp.SecureStorage.setItem('auth_token', 'eyJhbGciOi...', (error, success) => {
  if (error) {
    console.error('Secure storage failed:', error);
  } else {
    console.log('Token stored securely');
  }
});

getItem

Telegram.WebApp.SecureStorage.getItem(key, callback)

Reads the value of a specified key from secure storage.

Parameter	Type	Required	Description
key	String	Yes	Key name
callback	Function	Yes	Callback with (error, value) parameters

Telegram.WebApp.SecureStorage.getItem('auth_token', (error, value) => {
  if (error) {
    console.error('Read failed:', error);
  } else if (value) {
    // Use token
    apiClient.setToken(value);
  }
});

removeItem

Telegram.WebApp.SecureStorage.removeItem(key, callback)

Removes a specified key from secure storage.

Parameter	Type	Required	Description
key	String	Yes	Key name
callback	Function	No	Callback with (error, success) parameters

clear

Telegram.WebApp.SecureStorage.clear(callback)

Clears all data in secure storage.

Parameter	Type	Required	Description
callback	Function	No	Callback with (error, success) parameters

Storage Comparison

Feature	CloudStorage	DeviceStorage	SecureStorage
Location	Cloud	Local	Local (encrypted)
Data sync	Cross-device	Local only	Local only
Capacity	1024 keys × 4KB	5 MB	10 keys × 2KB
Security	Standard	Standard	Encrypted
Use cases	User preferences	Cache data	Sensitive data
Min version	—	Bot API 8.0+	Bot API 8.0+

Usage Example

const secureStorage = Telegram.WebApp.SecureStorage;

// Securely store login credentials
function saveCredentials(token, refreshToken) {
  secureStorage.setItem('access_token', token, (err) => {
    if (!err) {
      secureStorage.setItem('refresh_token', refreshToken);
    }
  });
}

// Load login credentials
function loadCredentials(callback) {
  secureStorage.getItem('access_token', (err, token) => {
    if (err || !token) {
      callback(null);
      return;
    }
    secureStorage.getItem('refresh_token', (err, refreshToken) => {
      callback({ token, refreshToken });
    });
  });
}

// Clear credentials on logout
function logout() {
  secureStorage.clear((err) => {
    if (!err) {
      console.log('Credentials cleared');
      redirectToLogin();
    }
  });
}