From: Christian Weiske Date: Sun, 14 Feb 2021 20:35:26 +0000 (+0100) Subject: Work in progress #1: Login steps 1-5 X-Git-Url: https://git.cweiske.de/tolino-api-docs.git/commitdiff_plain/18e52a23b272a10163c64281f3fec0ec82fe2805 Work in progress #1: Login steps 1-5 --- 18e52a23b272a10163c64281f3fec0ec82fe2805 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..daa30a3 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +README.html diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..c326848 --- /dev/null +++ b/README.rst @@ -0,0 +1,17 @@ +****************************** +Tolino cloud API documentation +****************************** + +Servers the Tolino Vision 3/4 HD talk to (Firmware 14.x). + +.. contents:: + :depth: 1 + +.. include:: headers.rst +.. include:: domains.rst +.. include:: login.rst +.. include:: pageplace.bosh-bosh-rest-ping.rst +.. include:: pageplace.bosh-bosh-rest-userid-xxx.rst +.. include:: pageplace.bosh-bosh-rest-v2-resellerconfig.rst +.. include:: thalia-auth-oauth2-authorize.rst +.. include:: thalia-auth-oauth2-token-post.rst diff --git a/domains.rst b/domains.rst new file mode 100644 index 0000000..caa9039 --- /dev/null +++ b/domains.rst @@ -0,0 +1,46 @@ +======= +Domains +======= +Domains that are used by the Tolino Vision 3 HD. + + +Buch.de +======= +``auth.buch.de`` + FIXME + + +Google +====== +``clients3.google.com`` + Check if the internet is reachable + + +MyTolino.com +============ +``management.mytolino.com`` + - List of resellers + - eInk handshake (FIXME) + + +Pageplace +========= +``bosh.pageplace.de`` + "bosh" could be short name for "BOokSHelf" + + - ping + - reseller configuration + - current time + - sync main data (books, reading status, notes) + - ebook upload + - ebook cover upload + +``cdp.pageplace.de`` + - Book images? + - Book downloads + +``family.pageplace.de`` + Family sharing + +``inventory.pageplace.de`` + FIXME diff --git a/headers.rst b/headers.rst new file mode 100644 index 0000000..0c40fb0 --- /dev/null +++ b/headers.rst @@ -0,0 +1,8 @@ +======= +Headers +======= + +``User-Agent`` + ``Dalvik/1.6.0 (Linux; U; Android 4.4.2; tolino Build/KOT49H)`` + + Used for normal API requests diff --git a/login.rst b/login.rst new file mode 100644 index 0000000..fbc3e9b --- /dev/null +++ b/login.rst @@ -0,0 +1,13 @@ +============= +Login process +============= + +This happens in the web browser. + +1. Fetch URL of login page: `GET https://thalia.de/auth/oauth2/authorize`_ +2. Show login page with username + password form +3. Redirect to internal e-book reader login with code. + + Example redirect: ``Location: epublishing://login?code=GK6jDC`` +4. Request OAuth access token: `POST https://thalia.de/auth/oauth2/token`_ +5. Fetch user data: `GET https://bosh.pageplace.de/bosh/rest/userid/xxx`_ diff --git a/pageplace.bosh-bosh-rest-ping.rst b/pageplace.bosh-bosh-rest-ping.rst new file mode 100644 index 0000000..187a71f --- /dev/null +++ b/pageplace.bosh-bosh-rest-ping.rst @@ -0,0 +1,17 @@ +=============================================== +``GET http://bosh.pageplace.de/bosh/rest/ping`` +=============================================== + +Used to check if the ebook reader is online (internet reachable). + +Request +======= +GET Parameters + ``responseStatus=204`` + Always there + + +Response +======== +Status Code + ``204 No Content`` diff --git a/pageplace.bosh-bosh-rest-userid-xxx.response.json b/pageplace.bosh-bosh-rest-userid-xxx.response.json new file mode 100644 index 0000000..6a33952 --- /dev/null +++ b/pageplace.bosh-bosh-rest-userid-xxx.response.json @@ -0,0 +1,9 @@ +{ + "initAppResponse": { + "config": null, + "deviceKey": null, + "update": 0, + "updateVersion": null, + "userId": "2086910932" + } +} diff --git a/pageplace.bosh-bosh-rest-userid-xxx.rst b/pageplace.bosh-bosh-rest-userid-xxx.rst new file mode 100644 index 0000000..e907e1e --- /dev/null +++ b/pageplace.bosh-bosh-rest-userid-xxx.rst @@ -0,0 +1,50 @@ +====================================================== +``GET https://bosh.pageplace.de/bosh/rest/userid/xxx`` +====================================================== +Step 5 in the `Login process`_. + +Example ``xxx`` value: ``665fc389ef4e47258c5db9fa7821bd19``. + +FIXME: What is the ``xxx`` value? Hardware ID? User ID? +If yes, where does the server know it from? + +FIXME: Find out how to transform the ``x_buchde.user_id`` from +`POST https://thalia.de/auth/oauth2/token`_ into that user ID here, +and if it is really the same. + + +Request +======= +No body in the request, despite the ``Content-Type`` header. + +Header + ``t_auth_token`` + OAuth token obtained from `POST https://thalia.de/auth/oauth2/token`_. + + Example: ``eyJhbGciOiJSUzI1NiJ9.eyJhdWRpZW5jZSI6InRyZWFkZXJ2aXNpb24zIiw...`` + ``Accept`` + ``application/json; charset=UTF-8`` + ``m_id`` + FIXME: Maybe reseller ID? + + Example: ``3`` + ``hardware_id`` + Seems to be the same as the ``xxx`` value in the URL. + + Example: ``665fc389ef4e47258c5db9fa7821bd19`` + ``Content-Type`` + ``application/json; charset=UTF-8`` + ``client_type`` + Example: ``TOLINO_VISION_3`` + ``client_version`` + Example: ``14.1.0`` + + +Response +======== +HTTP status code: ``200 OK`` + +Example: + +.. include:: pageplace.bosh-bosh-rest-userid-xxx.response.json + :code: diff --git a/pageplace.bosh-bosh-rest-v2-resellerconfig.html b/pageplace.bosh-bosh-rest-v2-resellerconfig.html new file mode 100644 index 0000000..b1f8281 --- /dev/null +++ b/pageplace.bosh-bosh-rest-v2-resellerconfig.html @@ -0,0 +1,44 @@ + + + + GET https://bosh.pageplace.de/bosh/rest/v2/resellerconfig + + + +
+

GET https://bosh.pageplace.de/bosh/rest/v2/resellerconfig

+
+

Request

+
+
Header
+
+
+
ifmodifiedsince
+
Example: 1603111725000
+
reseller_id
+
Example: 3
+
hardware_type
+
Example: tolino_vision_3
+
os_version
+
Android version Example: 4.4.2
+
language_code
+
Example: en
+
hardware_id
+
Example: 665fd389ea4e47228c5db8fa7821bd23
+
client_type
+
Example: TOLINO_VISION_3
+
client_version
+
+

Tolino firmware version

+

Example: 14.1.0

+
+
+
+
+
+
+

Response

+
+
+ + \ No newline at end of file diff --git a/pageplace.bosh-bosh-rest-v2-resellerconfig.response-ok.json b/pageplace.bosh-bosh-rest-v2-resellerconfig.response-ok.json new file mode 100644 index 0000000..ff9e0d3 --- /dev/null +++ b/pageplace.bosh-bosh-rest-v2-resellerconfig.response-ok.json @@ -0,0 +1,74 @@ +{ + "reseller_id": 3, + "client_type": "TOLINO_VISION_3", + "version": "1.7.0", + "lastModified": 1603111725000, + "config": { + "URL_HANDSHAKE": "https://management.mytolino.com/index.html?reseller=3&platform=eink", + "STRING_BRAND_NAME": "Thalia.de", + "URL_SHOP_EBOOK_SEARCH": "https://ereader.thalia.de/de.thalia.ers.sun/api/2004/sun/suche?einsprung=firmware&search_complex=", + "FAMILY_SHARING_ACTIVE": "true", + "LCP_ACTIVATED": "true", + "URL_SHOP_EBOOK_START_PAGE": "https://ereader.thalia.de/de.thalia.ers.sun/api/2004/sun/startseite?einsprung=firmware", + "SHOP_BASE": "https://ereader.thalia.de/de.thalia.ers.artikel/api/2004/artikel/details/?einsprung=reco", + "URL_OAUTH_ACCESSTOKEN_FAMILY": "https://thalia.de/auth/oauth2/token?client_secret=gU5a7CA9", + "IS_EXTERNAL_LINK_ENABLED": "true", + "URL_RESELLER_LOGO": "http://www.tpereader.thalia.de/logos/Prod/thalia_de_sw_klein.png", + "IS_LCP_ACTIVATED": "false", + "URL_BOOKSHELF": "https://bosh.pageplace.de/bosh/rest", + "OAUTH_CLIENT_ID": "treadervision3", + "ENABLE_DATA_RECOVERY": "true", + "URL_DEVICE_MANAGEMENT": "https://management.mytolino.com/index.html?reseller=3&platform=eink", + "URL_BROWSER_START_PAGE": "https://www.google.de", + "ADVERTISING_REDIRECT_BASE": "redirect.mytolino.com", + "URL_OAUTH_AUTHORIZATION": "https://thalia.de/auth/oauth2/authorize?response_type=code&scope=SCOPE_BOSH SCOPE_BUCHDE SCOPE_MANDANT_ID.2004 SCOPE_LOGIN FAMILY&redirect_uri=epublishing://login&x_buchde.skin_id=17", + "RECOMMENDATIONS_IS_SHUFFLE_ENABLED": "false", + "URL_OAUTH_ACCESSTOKEN": "https://thalia.de/auth/oauth2/token?client_secret=gU5a7CA9", + "URL_FAMILY_SHARING_MANUAL": "https://mytolino.de/family-sharing-handbuch-ereader", + "URL_OAUTH_REVOKETOKEN": "https://thalia.de/auth/oauth2/revoke" + }, + "configLanguageSpecific": [ + { + "language": "FR", + "languageConfig": { + "STRING_ARRAY_SUPPORT_CONTACT": "E-mail: info@thalia.de##Hotline: +49 (0) 251 530 94 44##(Du lundi au vendredi de 9 h à 18 h)", + "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Choisissez vos coups de cœur personnels parmi plus d'un million d'ebooks dans l'ebook-shop de Thalia.##Lisez parallèlement sur la tablette ou sur le smartphone avec l'appli eReading de Thalia.##Synchronisez vos ebooks en sécurité, confortablement et gratuitement à travers le tolino Cloud sur plusieurs appareils.##Avec votre tolino, utilisez gratuitement tous les hotspots de la Deutsche Telekom." + } + }, + { + "language": "EN", + "languageConfig": { + "STRING_ARRAY_SUPPORT_CONTACT": "E-Mail: info@thalia.de##Hotline: +49 (0)251 530 94 44##(German speaking customer care:##Monday to Friday, 9 a.m. to 6 p.m.)", + "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Browse through over 1,000,000 e-books in the Thalia shop.##Use the Thalia eBooks app to read in parallel on your tablet, computer or smartphone.##Synchronize your titles across various devices securely and free of charge via the tolino Cloud.##Use all Deutsche Telekom HotSpots free of charge with your tolino." + } + }, + { + "language": "ES", + "languageConfig": { + "STRING_ARRAY_SUPPORT_CONTACT": "E-Mail: info@thalia.de##Línea directa: +49 (0) 251 530 94 44##(Lunes a viernes de 9:00 a 18:00 horas)", + "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Seleccione de entre más de un millo de libros electrónicos en la tienda de eBooks de Thalia su destacados personalizados.##Lea de forma paralela con la aplicación de lectura digital de Thalia en su tableta o smartphone.##Sincronice sus libros electrónicos de forma segura, cómoda y gratuita a través de la tolino Cloud en distintos dispositivos.##Utilice con su dispositivo tolino de forma gratuita todos los HotSpots de la Deutsche Telekom." + } + }, + { + "language": "NL", + "languageConfig": { + "STRING_ARRAY_SUPPORT_CONTACT": "E-Mail: info@thalia.de##Hotline: +49 (0) 251 530 94 44##(Maandag t/m vrijdag 9:00 uur - 18:00 uur)", + "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Kies uit meer dan een miljoen ebooks in de Thalia eBook-Shop uw persoonlijke favorieten.##Lees met de Thalia eReading-app ook parallel op de tablet of smartphone.##Synchroniseer uw ebooks veilig, comfortabel en kosteloos via de tolino Cloud op verschillende apparaten.##Maak met uw tolino gratis gebruik van alle HotSpots van de Deutsche Telekom." + } + }, + { + "language": "DE", + "languageConfig": { + "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Wählen Sie aus über einer Million eBooks im Thalia eBook-Shop Ihre persönlichen Highlights.##Lesen Sie mit der Thalia eReading App auch parallel auf dem Tablet oder Smartphone.##Synchronisieren Sie Ihre eBooks sicher, komfortabel und kostenlos über die tolino Cloud auf verschiedenen Geräten.##Nutzen Sie mit Ihrem tolino alle HotSpots der Deutschen Telekom kostenlos.", + "STRING_ARRAY_SUPPORT_CONTACT": "E-Mail: info@thalia.de##Rufnummer: 0251 5309 444##(Montag bis Freitag 9 - 18 Uhr, Samstag 9:30 - 18 Uhr)" + } + }, + { + "language": "IT", + "languageConfig": { + "STRING_ARRAY_SUPPORT_CONTACT": "E-mail: info@thalia.de##Hot line: +49 (0) 251 530 94 44##(da lunedì a venerdì, dalle ore 9 alle ore 18)", + "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Scegli le tue letture preferite tra oltre un milione di eBook nell'eBook shop Thalia.##Con l'app Thalia eReading, leggi in parallelo anche sul tablet o lo smartphone.##Sincronizza i tuoi eBook in modo sicuro, comodo e gratuito su dispositivi diversi tramite tolino Cloud.##Con il tuo tolino, sfrutta gratis tutti gli hot spot di Deutsche Telekom." + } + } + ] +} diff --git a/pageplace.bosh-bosh-rest-v2-resellerconfig.rst b/pageplace.bosh-bosh-rest-v2-resellerconfig.rst new file mode 100644 index 0000000..d5944e7 --- /dev/null +++ b/pageplace.bosh-bosh-rest-v2-resellerconfig.rst @@ -0,0 +1,60 @@ +============================================================= +``GET https://bosh.pageplace.de/bosh/rest/v2/resellerconfig`` +============================================================= + +Fetch information about a given tolino reseller (shop): + +- Authentication URLs +- Browser start page +- Brand name ("Thalia.de") +- if LCP encryption is available + +etc. + + +Request +======= +Header + ``ifmodifiedsince`` + Timestamp with microseconds of last reseller config file version + + Example: ``1603111725000`` + ``reseller_id`` + Example: ``3`` + + Required. "400 Bad Request" if missing. + ``hardware_type`` + Example: ``tolino_vision_3`` + ``os_version`` + Android version + + Example: ``4.4.2`` + ``language_code`` + Example: ``en`` + ``hardware_id`` + Example: ``665fd389ea4e47228c5db8fa7821bd23`` + ``client_type`` + Example: ``TOLINO_VISION_3`` + + Required. "400 Bad Request" if missing. + ``client_version`` + Tolino firmware version + + Example: ``14.1.0`` + + +Response +======== + +``HTTP/1.1 304 Not Modified`` if the ``ifmodifiedsince`` header is equal or +later than the modification date. + + +Success +------- +``HTTP/1.1 200 OK`` for the content + +Example for headers ``reseller_id:3`` and ``client_type:TOLINO_VISION_3``: + +.. include:: pageplace.bosh-bosh-rest-v2-resellerconfig.response-ok.json + :code: diff --git a/thalia-auth-oauth2-authorize.rst b/thalia-auth-oauth2-authorize.rst new file mode 100644 index 0000000..894262a --- /dev/null +++ b/thalia-auth-oauth2-authorize.rst @@ -0,0 +1,44 @@ +=============================================== +``GET https://thalia.de/auth/oauth2/authorize`` +=============================================== +Fetch URL of actual login page. + +First step in the `Login process`_. + +Source +====== +This URL is provided in the reseller configuration, +key ``config.URL_OAUTH_ACCESSTOKEN``. + + +Request +======= +GET Parameters + ``response_type`` + Example: ``code`` + ``scope`` + Example: ``SCOPE_BOSH%20SCOPE_BUCHDE%20SCOPE_MANDANT_ID.2004%20SCOPE_LOGIN%20FAMILY`` + ``redirect_uri`` + Example: ``epublishing://login`` + ``x_buchde.skin_id`` + Example: ``17`` + ``client_id`` + Example: ``treadervision3`` +Headers + ``User-Agent`` + Browser user agent. + ``lcp`` + Example: ``1`` + ``X-Requested-With`` + Example: ``de.telekom.epub`` + + +Response +======== +Redirect to actual login page. + +Status code: HTTP/1.1 302 + +Header + ``Location``: + Example: ``https://thalia.de/de.thalia.ecp.authservice.application/oauth2/login?response_type=code&scope=SCOPE_BOSH%20SCOPE_BUCHDE%20SCOPE_MANDANT_ID.2004%20SCOPE_LOGIN%20FAMILY&redirect_uri=epublishing://login&x_buchde.skin_id=17&client_id=treadervision3`` diff --git a/thalia-auth-oauth2-token-post.html b/thalia-auth-oauth2-token-post.html new file mode 100644 index 0000000..4f50a8c --- /dev/null +++ b/thalia-auth-oauth2-token-post.html @@ -0,0 +1,88 @@ + + + + POST https://thalia.de/auth/oauth2/token + + + +
+

POST https://thalia.de/auth/oauth2/token

+
    +
  1. Log in to obtain an access token.
    2. +
  2. Generate access token from a refresh token.
    3. +
+

Step 4 of the `Login process`_.

+
+

Source

+

This URL is provided in the reseller configuration, key config.URL_OAUTH_ACCESSTOKEN.

+
+
+

Request

+
+
GET parameters
+
+
+
client_secret
+
+

Provided in the reseller configuration.

+

Example: gU5a7CA9

+
+
+
+
Headers
+
+
+
Content-Type
+
application/x-www-form-urlencoded
+
User-Agent
+
DT_EINK_10_NETRONIX DT_EINK_UPD_PP_14.1.0
+
Cookie:
+
Example: gcor=SIDYBbxYkmvUvoO8hy@2Sfx4QAAA9o; ab_bucket=9; ab_container=3; OAUTH-JSESSIONID=9C95C20ECEE74164E76F60C205147822.15acdb90
+
Cookie2
+
$Version=1
+
+
+
POST parameters
+
+
+
grant_type:
+
authorization_code
+
redirect_uri
+
+

epublishing://login

+

The e-reader internal login process

+
+
code
+
+

Obtained from login form page redirect.

+

Example: GK6jDC

+
+
client_id
+
Example: treadervision3
+
+
+
+
+
+

Response

+

HTTP status code 200 OK

+ 
{
+    "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJhdWRpZW5jZSI6InRyZWFkZXJ2aXNpb24zIiwiZXhwaXJlcyI6IjE2MTIxMzgzOTczMzMiLCJ4X2J1Y2hkZS51c2VyX2lk...",
+    "expires_in": 14399,
+    "refresh_token": "ad351547-bcb3-43b2-9914-d88f0a3704c8",
+    "scope": "FAMILY SCOPE_BOSH SCOPE_BUCHDE SCOPE_LOGIN",
+    "token_type": "bearer",
+    "x_buchde.mandant_id": "2004",
+    "x_buchde.user_id": "39549013"
+}
+
+
+
+

Docutils System Messages

+
+

System Message: ERROR/3 (thalia-auth-oauth2-token-post.rst line 7) id2

+

Unknown target name: "login process".

+
+
+ + \ No newline at end of file diff --git a/thalia-auth-oauth2-token-post.response.json b/thalia-auth-oauth2-token-post.response.json new file mode 100644 index 0000000..ce4646f --- /dev/null +++ b/thalia-auth-oauth2-token-post.response.json @@ -0,0 +1,9 @@ +{ + "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJhdWRpZW5jZSI6InRyZWFkZXJ2aXNpb24zIiwiZXhwaXJlcyI6IjE2MTIxMzgzOTczMzMiLCJ4X2J1Y2hkZS51c2VyX2lk...", + "expires_in": 14399, + "refresh_token": "ad351547-bcb3-43b2-9914-d88f0a3704c8", + "scope": "FAMILY SCOPE_BOSH SCOPE_BUCHDE SCOPE_LOGIN", + "token_type": "bearer", + "x_buchde.mandant_id": "2004", + "x_buchde.user_id": "39549013" +} diff --git a/thalia-auth-oauth2-token-post.rst b/thalia-auth-oauth2-token-post.rst new file mode 100644 index 0000000..55189a9 --- /dev/null +++ b/thalia-auth-oauth2-token-post.rst @@ -0,0 +1,50 @@ +============================================ +``POST https://thalia.de/auth/oauth2/token`` +============================================ +Step 4 of the `Login process`_. + +Uses: + +1. Log in to obtain an access token. +2. Generate access token from a refresh token. + + +Request +======= +GET parameters + ``client_secret`` + Provided in the reseller configuration. + + Example: ``gU5a7CA9`` + +Headers + ``Content-Type`` + ``application/x-www-form-urlencoded`` + ``User-Agent`` + ``DT_EINK_10_NETRONIX DT_EINK_UPD_PP_14.1.0`` + ``Cookie``: + Example: ``gcor=SIDYBbxYkmvUvoO8hy@2Sfx4QAAA9o; ab_bucket=9; ab_container=3; OAUTH-JSESSIONID=9C95C20ECEE74164E76F60C205147822.15acdb90`` + ``Cookie2`` + ``$Version=1`` + +POST parameters + ``grant_type``: + ``authorization_code`` + ``redirect_uri`` + ``epublishing://login`` + + The e-reader internal login process + ``code`` + Obtained from login form page redirect. + + Example: ``GK6jDC`` + ``client_id`` + Example: ``treadervision3`` + + +Response +======== +HTTP status code ``200 OK`` + +.. include:: thalia-auth-oauth2-token-post.response.json + :code: