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


API PRODUCTS

Call Verification API Connectivity API Location API

Step 4: Functional Call to API Resource

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

Introduction

This document guides the reader on how to make a functional call to a T-Mobile API Resource.

This is step 4 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


Some Important Things to Note

  1. All of T-Mobile's APIs require the PoP Token header ( X-Authorization), the Content-Type header (application/json), and Access Token header (Authorization) in the API header call.
  2. The PoP Token is only good for one hop and is only valid for 60 seconds. As a result, you must generate the Proof of Possession (PoP) Token over and over again in order to call both the OAuth 2.0 URI and the API Resource. T-Mobile recommends that you integrate one of our libraries that is compatible with your app in order to generate this PoP Token.
  3. The Access and ID Tokens are only valid for 3600 seconds or one hour. Please read the Step 2: Generate OAuth 2.0 Access and ID Tokens document to learn how to generate Access and ID Tokens.


API Resource Call

For demonstration purposes, we will use Connectivity API as the API Resource.

  1. Below is a GET cURL request for the Connectivity API resource based on the Swagger documentation.

    curl --location --request GET 'https://naas.t-mobile.com/iot-connectivity/v1/devices/<ICCID>' \
--header 'X-Authorization: <API_RESOURCE_POP_TOKEN_ARGUMENT>' \
--header 'Authorization: Bearer <ACCESS_TOKEN_FROM_OAUTH_2.0>' \
--header 'Content-Type: application/json' \
--data-raw ''

  2. Paste the OAuth 2.0 Access Token that you created in the Step 2: Generate OAuth 2.0 Access and ID Tokens into the Authorization header. Make sure this is a Bearer token.

    curl --location --request GET 'https://naas.t-mobile.com/iot-connectivity/v1/devices/89***************19' \
--header 'X-Authorization: <API_RESOURCE_POP_TOKEN_ARGUMENT>' \
--header 'Authorization: Bearer eyJraWQiOiI5ZmFiYjRmNy0xNTc0LTRhZTktYTc0Zi0wZTI5M2I3MTExOGUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJmOEE4RXhCZkcxaTRNVU9hWXZyYkFiRUNBNDZrTWNySyIsImF1ZCI6ImY4QThFeEJmRzFpNE1VT2FZdnJiQWJFQ0E0NmtNY3JLIiwiaXNzIjoiaHR0cHM6XC9cL2FwaS1kZXZzdGcudC1tb2JpbGUuY29tXC9vYXV0aDJcL3YxIiwiZXhwIjoxNjYxMjc5NDY3LCJpYXQiOjE2NjEyNzU4NjcsImp0aSI6ImU4ZmI3M2Q5LTkyZjUtNDVlMS1hNjNlLWVjMTBkYzEzZGM2OCJ9.AAKQFCT6ST1rdYQclDYz5UDVynFPfQ7bb8UuhAy5yorJn7chDAvK119kjFqQc42m-sMfxBNVgVtb1zyVu66AG40m-tj98680oIvVt0-4mWO483KEpNFZ1JIXmiUXKtu1_nf_YDTEb4np4f6K7Bm-o2b2rcwqZEvLyQevUNBhz1p5EiPD2LDyiuXtSJ47mWaxhVxwEFKDUSDCAW2ZVDIX_JfIChabiExcDtbFZQVWsAybDW6y6Imsn2-fr8EmoAy2vDaO1hNlkh6n75BUZleVtx8aTgus6bAZ2F2I8fQFNqEqdBXkeHB-mrV6kvy6EhQdvvtzxcgatGhly6e3kksxzQ' \
--header 'Content-Type: application/json' \
--data-raw ''

  3. Paste the API Resource PoP Token that you created in Step 3: Generate PoP Token - API Resource document into the X-Authorization header. 

    curl --location --request GET 'https://naas.t-mobile.com/iot-connectivity/v1/devices/89***************19' \
--header 'X-Authorization: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlZHRzIjoiQ1pFSUpUOWs4REd0UUtVQkdGd2NkNW5CR3pUSGloTFg0Z2E0ekRGcm9wUSIsInYiOiIxIiwiZXhwIjoxNjY3OTUwNDUyLCJlaHRzIjoiQ29udGVudC1UeXBlO0F1dGhvcml6YXRpb247dXJpO2h0dHAtbWV0aG9kO2JvZHkiLCJpYXQiOjE2Njc5NTAzMzIsImp0aSI6ImM1YmViNWEzLWE4ZmEtNTE3Zi03MGNkLTk5ZGRmM2EwZjJkYSJ9.nGlpQH6Rkjwvmql10b9RjplRt-YP9vL55sMIt2D2RigUWy39j1UL3UPJMzlRXJ8b9UWG6ae7CsCJwLQ1tJq6OUW2T_2H50KWxpLfKZCPpI8B_JSOl7N-PUtg7gYgc2wcUii5dgAMa3gH74vJYbkPqXct-y1T-zSbTCoC86Wc8PxA72ifOPP210035QH0v4s72DzuRqnM06owkCyKBM3FjUjJWZdCdd7gcvAPt_OwBW62FsoqXeVa88Pz53ejOrlp5NZawwngC1WU9qsnv0rPueMVFPEyNAlCPX2kx5_oRFLoB7UjS559_2QKFGjAmGbkqqu_aquLOK9mo3uSI0WQow' \' \
--header 'Authorization: Bearer eyJraWQiOiI5ZmFiYjRmNy0xNTc0LTRhZTktYTc0Zi0wZTI5M2I3MTExOGUiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJmOEE4RXhCZkcxaTRNVU9hWXZyYkFiRUNBNDZrTWNySyIsImF1ZCI6ImY4QThFeEJmRzFpNE1VT2FZdnJiQWJFQ0E0NmtNY3JLIiwiaXNzIjoiaHR0cHM6XC9cL2FwaS1kZXZzdGcudC1tb2JpbGUuY29tXC9vYXV0aDJcL3YxIiwiZXhwIjoxNjYxMjc5NDY3LCJpYXQiOjE2NjEyNzU4NjcsImp0aSI6ImU4ZmI3M2Q5LTkyZjUtNDVlMS1hNjNlLWVjMTBkYzEzZGM2OCJ9.AAKQFCT6ST1rdYQclDYz5UDVynFPfQ7bb8UuhAy5yorJn7chDAvK119kjFqQc42m-sMfxBNVgVtb1zyVu66AG40m-tj98680oIvVt0-4mWO483KEpNFZ1JIXmiUXKtu1_nf_YDTEb4np4f6K7Bm-o2b2rcwqZEvLyQevUNBhz1p5EiPD2LDyiuXtSJ47mWaxhVxwEFKDUSDCAW2ZVDIX_JfIChabiExcDtbFZQVWsAybDW6y6Imsn2-fr8EmoAy2vDaO1hNlkh6n75BUZleVtx8aTgus6bAZ2F2I8fQFNqEqdBXkeHB-mrV6kvy6EhQdvvtzxcgatGhly6e3kksxzQ' \
--header 'Content-Type: application/json' \
--data-raw ''

  4. Update the request body to match the API Resource PoP Token EXACTLY. If any of the fields do no match the API Resource PoP Token EXACTLY the API Resource call will break. In this case there is no request body, however, if any spaces or carriage returns are added to the request body the API Resource call will break.

  5. Import the above cURL request into Postman.

  6. Click Send.

  7. When you have generated your PoP Tokens and Access Token properly, the resulting response will be a 200 OK message, just like the Connectivity API swagger specified. In addition, there will be information regarding the device in the response body. In other words, the functional call to the API Resource was a success.

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 - Can I use my OAuth 2.0 Access Token on multiple hops and multiple API Resources?
  • Answer 1 - Yes you can.


  • Question 2 - Is there a tutorial to teach me how to use the PoP Token Library?
  • Answer 2 - At the time of this writing no.


  • Question 3 - Can I do the TAAP steps out of order?
  • Answer 3 - No you cannot. The OAuth 2.0 PoP Token must be generated first, then the Access Token, then the API Resource PoP Token, before you can complete this fourth step.