Telegram Passport is a unified authorization method for services that require personal identification. Users can upload their documents once, then instantly share their data with services that require real-world ID (finance, ICOs, etc.). Telegram doesn't have access to the users' personal information thanks to end-to-end encryption.
From the perspective of a service that requires real-world ID, the process looks like this:
Check out this example to see Telegram Passport in action.
To learn more about Telegram Passport from the perspective of a user, please see this blog post and the technical MTProto documentation. See this page if you're interested in encryption algorithms used on Telegram's side.
Telegram Passport 1.1 (blog post)
To integrate Telegram Passport into your login or verification flow, you need a working Telegram bot (see this page for information on how to get one).
To request data from Telegram Passport users, your bot will need to generate a pair of encryption keys.
First, use a console to generate a private key:
openssl genrsa 2048 > private.key
WARNING: Keep your private key SECRET!
Then use the console to print the corresponding public key:
openssl rsa -in private.key -pubout
Use the /setpublickey command with @BotFather to connect this public key with your bot.
Add a link to your Privacy Policy by using the /setprivacypolicy command. Users will see this link when offered to authorize you to access their data.
To request information stored in a Telegram Passport, use one of these SDKs:
Use the following parameters to request information with the SDK:
Parameters | Type | Required |
bot_id | Integer | Yes |
scope | PassportScope | Yes |
public_key | String | Yes |
nonce | String | Yes |
This object represents the data to be requested.
Field | Type | Description |
data | Array of PassportScopeElement | List of requested elements, each type may be used only once in the entire array of PassportScopeElement objects |
v | Integer | Scope version, must be 1 |
This object represents a requested element, should be one of:
This object represents several elements one of which must be provided.
Field | Type | Description |
one_of | Array of PassportScopeElementOne | List of elements one of which must be provided; must contain either several of “passport”, “driver_license”, “identity_card”, “internal_passport” or several of “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration” |
selfie | Boolean | Optional. Use this parameter if you want to request a selfie with the document from this list that the user chooses to upload. |
translation | Boolean | Optional. Use this parameter if you want to request a translation of the document from this list that the user chooses to upload. Note: We suggest to only request translations after you have received a valid document that requires one. |
This object represents one particular element that must be provided. If no options are needed, String can be used instead of this object to specify the type of the element.
Field | Type | Description |
type | String | Element type. One of "personal_details", "passport", "driver_license", "identity_card", "internal_passport", "address", "utility_bill", "bank_statement", "rental_agreement", "passport_registration", "temporary_registration", "phone_number", "email" |
selfie | Boolean | Optional. Use this parameter if you want to request a selfie with the document as well. Available for "passport", "driver_license", "identity_card" and "internal_passport" |
translation | Boolean | Optional. Use this parameter if you want to request a translation of the document as well. Available for "passport", "driver_license", "identity_card", "internal_passport", "utility_bill", "bank_statement", "rental_agreement", "passport_registration" and "temporary_registration". Note: We suggest to only request translations after you have received a valid document that requires one. |
native_names | Boolean | Optional. Use this parameter to request the first, last and middle name of the user in the language of the user's country of residence. Available for "personal_details" |
You can also use the special type "id_document" as an alias for one of "passport", "driver_license", "identity_card" and the special type "address_document" as an alias for one of "utility_bill", "bank_statement", "rental_agreement".
So {"type":"id_document",selfie:true}
is equal to {"one_of":["passport","driver_license","identity_card"],selfie:true}
.
Your bot can request personal details, one or several types of identity document, residential address, one or several types of proof of address document, a phone number, or an email address. You can also request optional selfies with the document and certified English translations of the document. This is just a list of data types that can be requested, and the encrypted objects that will contain such data.
Note: We suggest to only request English translations after you have received a valid document that requires one.
Name | Key | Type | Description |
---|---|---|---|
personal_details | data | PersonalDetails | Personal Details |
passport | data | IdDocumentData | Passport |
front_side | PassportFile | ||
selfie | Optional. PassportFile | ||
translation | Optional. Array of PassportFile | ||
internal_passport | data | IdDocumentData | Internal Passport |
front_side | PassportFile | ||
selfie | Optional. PassportFile | ||
translation | Optional. Array of PassportFile | ||
driver_license | data | IdDocumentData | Driver License |
front_side | PassportFile | ||
reverse_side | PassportFile | ||
selfie | Optional. PassportFile | ||
translation | Optional. Array of PassportFile | ||
identity_card | data | IdDocumentData | Identity Card |
front_side | PassportFile | ||
reverse_side | PassportFile | ||
selfie | Optional. PassportFile | ||
translation | Optional. Array of PassportFile | ||
address | data | ResidentialAddress | Address |
utility_bill | files | Array of PassportFile | Utility Bill |
translation | Optional. Array of PassportFile | ||
bank_statement | files | Array of PassportFile | Bank Statement |
translation | Optional. Array of PassportFile | ||
rental_agreement | files | Array of PassportFile | Rental Agreement |
translation | Optional. Array of PassportFile | ||
passport_registration | files | Array of PassportFile | Registration Page in the Internal Passport |
translation | Optional. Array of PassportFile | ||
temporary_registration | files | Array of PassportFile | Temporary Registration |
translation | Optional. Array of PassportFile | ||
phone_number | String | Phone number | |
String |
This object represents personal details.
Field | Type | Description |
first_name | String | First Name |
last_name | String | Last Name |
middle_name | String | Optional. Middle Name |
birth_date | String | Date of birth in DD.MM.YYYY format |
gender | String | Gender, male or female |
country_code | String | Citizenship (ISO 3166-1 alpha-2 country code) |
residence_country_code | String | Country of residence (ISO 3166-1 alpha-2 country code) |
first_name_native | String | First Name in the language of the user's country of residence |
last_name_native | String | Last Name in the language of the user's country of residence |
middle_name_native | String | Optional. Middle Name in the language of the user's country of residence |
This object represents a residential address.
Field | Type | Description |
street_line1 | String | First line for the address |
street_line2 | String | Optional. Second line for the address |
city | String | City |
state | String | Optional. State |
country_code | String | ISO 3166-1 alpha-2 country code |
post_code | String | Address post code |
This object represents the data of an identity document.
Field | Type | Description |
document_no | String | Document number |
expiry_date | String | Optional. Date of expiry, in DD.MM.YYYY format |
This object represents a PassportFile related to a document. The file is up to 10 MB in size and in the .jpg format.
When the user confirms your request by pressing the "Authorize" button, the Bot API sends an Update with the field passport_data to the bot that contains encrypted Telegram Passport data.
Note that all base64-encoded fields should be decoded before use.
To decrypt the received data, first, decrypt the credentials contained in EncryptedCredentials.
Decrypt the credentials secret ( secret field in EncryptedCredentials) using your private key (set OAEP padding option, e.g. OPENSSL_PKCS1_OAEP_PADDING
in PHP)
Use this secret and the credentials hash ( hash field in EncryptedCredentials) to calculate credentials_key and credentials_iv as described below:
credentials_secret_hash = SHA512( credentials_secret + credentials_hash )
credentials_key = slice( credentials_secret_hash, 0, 32 )
credentials_iv = slice( credentials_secret_hash, 32, 16 )
Decrypt the credentials data ( data field in EncryptedCredentials) by AES256-CBC using these credentials_key and credentials_iv. IMPORTANT: At this step, make sure that the credentials hash is equal to SHA256( credentials_data )
Credentials data is padded with 32 to 255 random padding bytes to make its length divisible by 16 bytes. The first byte contains the length of this padding (including this byte). Remove the padding to get the data.
Note that all hashes represent as raw binary data, not hexits
Credentials is a JSON-serialized object.
Field | Type | Description |
secure_data | SecureData | Credentials for encrypted data |
nonce | String | Bot-specified nonce |
IMPORTANT: Make sure that the nonce is the same as was passed in the request.
This object represents the credentials required to decrypt encrypted data. All fields are optional and depend on fields that were requested.
Field | Type | Description |
personal_details | SecureValue | Optional. Credentials for encrypted personal details |
passport | SecureValue | Optional. Credentials for encrypted passport |
internal_passport | SecureValue | Optional. Credentials for encrypted internal passport |
driver_license | SecureValue | Optional. Credentials for encrypted driver license |
identity_card | SecureValue | Optional. Credentials for encrypted ID card |
address | SecureValue | Optional. Credentials for encrypted residential address |
utility_bill | SecureValue | Optional. Credentials for encrypted utility bill |
bank_statement | SecureValue | Optional. Credentials for encrypted bank statement |
rental_agreement | SecureValue | Optional. Credentials for encrypted rental agreement |
passport_registration | SecureValue | Optional. Credentials for encrypted registration from internal passport |
temporary_registration | SecureValue | Optional. Credentials for encrypted temporary registration |
This object represents the credentials required to decrypt encrypted values. All fields are optional and depend on the type of fields that were requested.
Field | Type | Description |
data | DataCredentials | Optional. Credentials for encrypted Telegram Passport data. Available for "personal_details", "passport", "driver_license", "identity_card", "internal_passport" and "address" types. |
front_side | FileCredentials | Optional. Credentials for an encrypted document's front side. Available for "passport", "driver_license", "identity_card" and "internal_passport". |
reverse_side | FileCredentials | Optional. Credentials for an encrypted document's reverse side. Available for "driver_license" and "identity_card". |
selfie | FileCredentials | Optional. Credentials for an encrypted selfie of the user with a document. Available for "passport", "driver_license", "identity_card" and "internal_passport". |
translation | Array of FileCredentials | Optional. Credentials for an encrypted translation of the document. Available for "passport", "driver_license", "identity_card", "internal_passport", "utility_bill", "bank_statement", "rental_agreement", "passport_registration" and "temporary_registration". |
files | Array of FileCredentials | Optional. Credentials for encrypted files. Available for "utility_bill", "bank_statement", "rental_agreement", "passport_registration" and "temporary_registration" types. |
These credentials can be used to decrypt encrypted data from the data field in EncryptedPassportElement.
Field | Type | Description |
data_hash | String | Checksum of encrypted data |
secret | String | Secret of encrypted data |
To decrypt data, use the corresponding secret and data_hash from DataCredentials as described below:
data_secret_hash = SHA512( data_secret + data_hash )
data_key = slice( data_secret_hash, 0, 32 )
data_iv = slice( data_secret_hash, 32, 16 )
Use AES256-CBC with this data_key and data_iv to decrypt the data (the data field in EncryptedPassportElement). IMPORTANT: At this step, make sure that data_hash from the credentials is equal to SHA256( data )
.
The data is padded with 32 to 255 random padding bytes to make its length divisible by 16 bytes. The first byte contains the length of the padding (including this byte). Remove padding to get the data.
The data is a JSON-serialized object of one of the following types: PersonalDetails, IdDocumentData, ResidentialAddress, depending on type.
These credentials can be used to decrypt encrypted files from the front_side, reverse_side, selfie, files and translation fields in EncryptedPassportElement.
Field | Type | Description |
file_hash | String | Checksum of encrypted file |
secret | String | Secret of encrypted file |
To decrypt the file, use the corresponding secret and file_hash from FileCredentials as described below:
file_secret_hash = SHA512( file_secret + file_hash )
file_key = slice( file_secret_hash, 0, 32 )
file_iv = slice( file_secret_hash, 32, 16 )
Download the encrypted file using the getFile method.
Use AES256-CBC with this file_key and file_iv to decrypt the content of the file. IMPORTANT: At this step, make sure that file_hash from the credentials is equal to SHA256( file_content )
.
The content of the file is padded with 32 to 255 random padding bytes to make its length divisible by 16 bytes. The first byte contains the length of the padding (including that byte). Remove padding to get the file content.
If the data you received contains errors, the bot can use the setPassportDataErrors method to inform the user and request information again. The user will not be able to resend the data, until all errors are fixed.