API SECURITY

API Security Home Quick Start T-Mobile API Overview Token Overview Step 1:
Generate PoP Token - OAuth 2.0 Step 2:
Generate OAuth 2.0 Access and ID Tokens Step 3:
Generate PoP Token - API Resource Step 4:
Functional Call to API Resource Server Formats Status Code Definitions

Step 3: Generate a PoP Token - API Resource

Home / Portfolio / Content / Technical Writing / API Security / Step 3

Introduction

This document guides the reader on how to create a T-Mobile proprietary Proof of Possession (PoP) API Resource Token.

This is step 3 of 4 in the T-Mobile API Access Protocol (TAAP) process. To learn more about the TAAP process, please read the documents T-Mobile API Overview and Token Overview.


Prerequisites

  1. A DevEdge Account. If you do not have a DevEdge account please create one now.
  2. Be subscribed to the API resource you are about to request. Please check the subscription page to understand if you are subscribed to the API or not.
  3. You completed all the steps in the Step 1: Generate PoP Token - OAuth 2.0 first.
  4. You completed all the steps in the Step 2: Generate OAuth 2.0 Access and ID Tokens second.
  5. A computer with a web browser.
  6. Internet access.

Some Important Things to Note

  1. This walkthrough will teach you:
    1. How to generate an API Resource PoP Token.
  2. Note that there are two different types of Proof of Possession (PoP) tokens.
    1. An OAuth 2.0 PoP Token
    2. An API Resource PoP Token

  3. When developing a Java, JavaScript, or .NET client, we recommend using a TAAP PoP Token Creation Library developed by T-Mobile. In the case of other languages (e.g. Python, PHP, etc.) the code should create a JSON object in the format mentioned in TAAP documentation. An example can be seen below.

    Header: {alg, type}
Body {
  iat: <epoch time>
  exp: <epoch time>
  ehts: <authorization; content_type; uri; http-method; body> => All request headers, URI, HTTP method and body fields used to create hash
  edts: <Base64UrlSafeEncoding[SHA256(all ehts claim values as a concatenated string)]">
  jti: <unique identifier>
  v: "1"
}
Signature: <digitalSignature>
  4. A new PoP token needs to be created for each API Resource request because the PoP Token is only good for one hop / call and 60 seconds.

Generate the API Resource PoP Token

  1. In Finder app, navigate to the html_example folder in the JavaScript PoP Token library (js-lib-tmobile-oss-poptoken-builder) folder.

  2. Open the poptoken-builder-text.html in a web browser.

  3. Update the poptoken-builder-text.htmlfile thusly.

    1. Content-Type must be application/json.

    2. Authorization must be a "Bearer" token and the access token you generated from the Step2: Generate OAuth 2.0 Access and ID Tokens document.

    3. URI must be set to the API Resource's endpoint. For demonstration purposes we will use the Connectivity API. Based on the API Specifications the URI endpoint should be /iot-connectivity/v1/devices/{ICCID}.

    4. HTTP-Method must be set to GET.

    5. Body should be set to whatever the request body of your API call is. In the case of the Connectivity API the request body is left blank.

    6. Note that these fields need to match the API call EXACTLY or the PoP Token will break. No extra spaces, carriage returns, or characters are allowed. And text case does matter. If the method is GET, all upper case, then ensure that the HTTP-Method is spelled all upper-case, GET.

      BEFORE

      AFTER

  4. Click Generate PoP Token.

  5. Note that the above PoP Token will only be viable for 60 seconds. Also note that the Proof of Possession (PoP) Token is only good for one hop. You cannot use this PoP token on any other call.
  6. Copy the PoP token and move onto the Step 4: Functional Call to API Resource Server document.

Troubleshooting

  • Issue 1- I am receiving errors when sending a request to the API Resource. Is there a list of status codes that I can look at that can help me debug?
  • Solution 1- Yes there is. Please read the Status Codes Definitions document to learn more.


  • Issue 2 - I cannot find my ICCID. Where can I find this?

  • Solution 2 - Check in your "safe spot" for your ICCID. In the document Step 1: Generate PoP Token - OAuth 2.0 > Step A > Number 10, you were asked to put the ICCID in a safe spot. Please check that spot now for your ICCID.

    In addition, if the SIM card is installed in your T-Mobile DevEdge IoT Developer Kit you can always use the command tmo modem 1 iccid to find the ICCID.

FAQ

  • Question 1 - Are there tutorials for the other PoP Token Libraries?
  • Answer 1 - As of this writing there are not.


  • Question 2 - Can I skip step 1 and 2 and still successfully create an API Resource PoP Token?
  • Answer 2 - No, you cannot. All steps must be done in the assigned order if you wish to create an API Resource PoP Token, let alone make a successful API call to one of T-Mobile's API Resources.