Quick Start

Home / Portfolio / Content / Technical Writing / API Security / Quick Start

Introduction

This document will help the reader make a quick call to one of our (T-Mobile's) APIs. This guide WILL NOT teach you how the T-Mobile API security and protocol processes work. ONLY how to get a quick API call working.

Prerequisites

Postman installed on your computer.
An understanding of OpenSSL public and private keys.

Why would I want to implement the instructions in this document?

The T-Mobile API Access Protocol (TAAP) has many steps that can be automated. This Postman collection and environment aims to help with this automation.

Some Important Things to Note

T-Mobile provides this Postman collection and environment in an "AS IS" basis, without warranties or conditions of any kind, express or implied.

Configuration

Step A

Create a DevEdge Account.

Go to https://devedge.t-mobile.com > Login.
Click Sign up.
Fill out the form then click Create Account.
Check your email address for the 6-digit access code, enter it in the text box, then click Continue.

Selecting the "Remember this device box" will remove the need to check your email address again for a 6-digit verification code in the future.
Click Agree and continue.
Click Continue on the welcome screen.
At this point you are required to create an account type. Select one, check the box to agree to the Terms of Service, then click Continue.
If you selected Enterprise, enter a company name then click Continue. Selecting the account type Individual skips steps 9 through 12.
If the enterprise company name does not exist you will be asked if it is okay to create the company name. Click Create Company.
Next you are required to create a group. Click Create new group.
Name it whatever you wish then click Next.
Add other team members if you wish or simply click Create Group.
Click Continue.
Once you are finished you will be taken to a Welcome to T-Mobile DevEdge screen. Click Account dashboard.

Step B

Subscribe to an API.

Subscribe to an API. For demonstration purposes we will purchase an IoT Developer Kit which automatically comes with the Connectivity API. To purchase the IoT Developer Kit go here.
Click Start building. Note you must be logged into DevEdge in order to purchase the kit.
Subscribe to other available APIs if desired then click Next.
Add a Billing Address, Payment Method, scroll down, check the Terms and Conditions checkbox, then click Pay now.
Click Account dashboard.
Click Activate kit.
Save your IMEI and ICCID in a safe place then click Activate.
Click Done.
Go to the Subscription page.
Click the ellipsis next to a subscribed API then click View API keys.
Your API client ID and client secret appears in the window.
Copy them and save them in a safe place.

Step C

Create OpenSSL Public and Private Keys

Install node.js.

Download the following JavaScript file onto your Desktop: index_create_key_pair.js

The code for this JavaScript file can also be found below:

/*
* Copyright 2019 T-Mobile US, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*     http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

const { generateKeyPair } = require('crypto');
var fs = require("fs");

generateKeyPair('rsa', {
  modulusLength: 2048,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem'
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem'
  }
}, (err, publicKey, privateKey) => {
  fs.writeFile('public-key.txt', publicKey, (err) => {
   if (err) {
      throw err;
   } else {
    console.log('The public-key.txt file has been saved.');
    }
});

fs.writeFile('private-key.txt', privateKey, (err) => {
   if (err) {
       throw err;
    } else {
    console.log('The private-key.txt file has been saved.');
    }
  });
});

Open your command line app. For demonstration purposes we will be using Terminal on a Mac.
Change directories to your Desktop.
Type node index_create_key_pair.js then press Return on your keyboard.
On your Desktop both a public and private key is generated.
Login to DevEdge.
Go to the Subscription page.
Click the ellipsis next to a subscribed API then click View API keys.
Click Add key.
Open the public-key.txt file that you created in step 5. Select all the text in the file.
Paste the public key into the text area then click Add key.

Paste the entire contents of the public-key.txt into the text area, including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----, or the PoP Token will not work. Also remember to avoid adding any spaces.
You should receive a message that your public key was updated successfully.

Step D

Import the Postman collection and environment.

Download the Postman collection JSON here.
Download the Postman environment JSON here.
Open Postman.
Click Import then Choose Files.
Navigate to where the files were downloaded onto your computer, select the JSON files, then click Open.
Click Import.
The collection and the environment are now imported.
Click on No Environment then select T-Mobile-TAAP-Collection-Environment-updated.

Step E

Add the client ID, client secret, and private key to the Postman environment.

In Postman, click Environments.
Select T-Mobile-TAAP-Collection-Environment-updated.
Enter your client ID, client secret, and private key (private-key.txt) in the CURENT VALUE column then click Save.

Step F

Make a call to a subscribed to API.

Click on Collections.
Select T-Mobile-TAAP-Collection-updated.
Select 1-PoP_Token_Creation.
Select OAuth 2.0.
Click Send. An access_token is generated.
Select Connectivity > GET Connectivity.
Replace the {{ICCID}} with your ICCID. Or add the ICCID to the T-Mobile-TAAP-Collection-Environment-updated environment.
The response body should be filled with detailed information about the device. Cross reference the response body with the Connectivity API documentation.
Select the next API that you are subscribed to, replace any parameters as needed, then click Send.
Remember to reference the documentation to understand the response that you should be receiving. Some APIs require that you change the ICCID in the path. Others require that you change query parameters.

Troubleshooting

Issue 1 - I am getting an error that the PoP Token is expired. Why is this happening?
Solution 1 - The PoP Token is only valid for 60 seconds. Use the OAuth 2.0 and generate a new access_token. This could help fix the problem.

FAQ

Question 1 - Do you have a list of status code messages that the APIs will respond with?
Answer 1 - Yes, please read our Status Code Definitions document found here.

Question 2 - Is there another way to generate a public and private key?
Answer 2 - Yes there is. You can use the Shining Light Production installation files. Note that this method will only work on a Windows OS.
1. Download the Shining Light Production installation files then install them on your Windows based computer.
2. Search for the OpenSSL command line app then open it.
3. Enter the following at OpenSSL command line to generate your RSA public and private keys using the following commands.
```
# Creates private key in PKCS1 format
openssl genrsa -out private-key-pkcs1.pem 2048

# Converts private key to PKCS8 format
openssl pkcs8 -topk8 -inform PEM -in private-key-pkcs1.pem -outform PEM -nocrypt -out private-key-pkcs8.pem

# Creates public key in PKCS8 format
openssl rsa -in private-key-pkcs8.pem -outform PEM -pubout -out public-key.pem
```
4. The following files are created after running the above OpenSSL commands.
5. Save the private-key-pkcs8.pem. You will need it to generate the PoP Token.
6. Open the public-key.pem with a text app, select all the text, then copy the public key text.
  
  Copy the entire contents of the public key, including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----, or the PoP Token will not work.
7. Login to DevEdge.
8. Navigate to the subscription page
9. Click the ellipsis next to a subscribed API, click View API keys, click Add key, paste your public key into the text area, then click Add key again.
  
  Paste the entire contents of the public key into the text area, including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----, or the PoP Token will not work.