VPaaS Platform Token

This readme will provide you with all the needed information to generate a User Token (aka Voice Platform Token) by yourself.

As we are working with the production environment, currently generating a static token for an anonymous user is not supported.

Why are we doing this?

In order to call any Voice API endpoint you need to provide a User Token within the HTTP Header Field Authorizationin the below format Authorization: Bearer THE_REALLY_LONG_ENCRYPTED_USER_TOKEN.

Note: You can also find the endpoint in the swagger documentation under API tab of https://developer.telekom.com/.

Generate Platform Token

There are a couple of steps to generate a token:

Get an IDM Account
Trigger the login
Exchange the auth code for the VPaaS (Voice Platform as a Service) Token
Use the token
Refresh the token (Optional)

0. IDM Account

An IDM (Identity Management system for end users of speakers, etc.) Account is needed to login to the platform. This account can be also created for free at the official registration page

One must provide a valid mobile phone number to verify the registration. Everything else is free of charge.

1. Trigger the login

You can trigger the login by calling the following endpoint:

/user/api/v2/login?clientId=XXX

The curl will look like the following:

curl -X GET "https://api.voiceui.telekom.net/user/api/v2/login?clientId=THE_CLIENT_ID&scope=THE_SCOPE" \
-H  "apikey: THE_API_KEY"

Note: CompApp is usually used in the placeholder THE_SCOPE

you will get a redirect url which should be opened in the browser e.g.:

Redirect to https://accounts.login00.idm.ver.sul.t-online.de/oauth2/auth?prompt=x-no-sso&response_type=code&scope=offline_access%20smarthub&client_id=10T.......00&redirect_uri=https://........de/user/api/v2/login-complete&state=eyJhbG........tmITQRA1E

Please copy and paste this url and open it in your browser of choice. After you login, you will automatically be redirected to a similar url schema as following:

smarthubplatform://login?authCode=<needed for next step>

2 Exchange the auth code for the VPaaS Platform Token

You need to copy and paste the content of the authCode from the previous step and call the user/api/v2/exchange-auth-code endpoint

A curl would look like:

curl -X POST "https://api.voiceui.telekom.net/user/api/v2/exchange-auth-code" \
      -H  "apikey: THE_API_KEY" \
      -H  "Content-Type: application/json" \
      -d "{  \"authCode\": \"THE_AUTH_CODE\",  \"clientId\": \"THE_CLIENT_ID\"}"

The response of this request should be the VPaaS Platform Token:

{
   "accessToken": "eyJhbGciOiJ..........nV3POfgARffP_fs",
   "refreshToken": "XXXXX",
   "expiresIn ": 14399,
   "expiresAt ": "2020 - 11 - 25 T16: 43: 11.219846 Z ",
   "scope ": "XXXX"
}

3 Use the token

To check if the token is valid you can call the user info endpoint:

Request:

curl "https://api.voiceui.telekom.net/user/api/v1/" \
     -H 'apikey: THE_API_KEY' \
     -H 'Authorization: Bearer eyJhbGciOiJ..........nV3POfgARffP_fs'

Response:

{"id":"12...05","anonymizedId":"oMz..7R2","name":"s...@t-online.de","email":"s...@t-online.de","personalDataUrl":"https://............./index.xhtml","flags":["/feature/mss/mailbox_allowed"]}

4 Refresh the token (Optional)

To refresh the token simple call the /user/api/v2/refresh-platform-token endpoint

Example:

curl -X POST "https://api.voiceui.telekom.net/user/api/v2/refresh-platform-token" \
      -H 'apikey: THE_API_KEY' \
      -H  "Content-Type: application/json" \
      -d "{  \"clientId\": \"THE_CLIENT_ID\",  \"refreshToken\": \"RTSVH2:eyJhb.......OfgARffP_fs\"}"

Response:

{
  "accessToken": "eyJhbGc.......HuRxVM",
  "refreshToken": "RTSV........3Bao",
  "expiresIn": 14399,
  "expiresAt": "2020-11-25T17:17:09.260099Z",
  "scope": "THE_SCOPE"
}

Getting IDM Token