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

T-Mobile API Overview

Home / Portfolio / Content / Technical Writing / API Security / T-Mobile API Overview

Introduction

This document gives an overview of what T-Mobile's API authentication protocols are and how to get through them. Note that this is the long AND extremely detailed explanation of how T-Mobile's API Security authentication works. Once you read this and the following documents ...

... you should be able to implement this on your development, staging, and production servers.

If all you are interested in is making a quick call to one of T-Mobile's APIs and getting data back this document IS NOT for you. Please read the Quick Start document instead.

What does T-Mobile call its API Security Protocol?

T-Mobile calls its API Security Protocol TAAP. This acronym stands for T-Mobile API Access Protocol.

TAAP uses a combination of Open ID Connect (OIDC) and OAuth 2.0 during its API security authentication process.

How does T-Mobile's API Security Protocol differ from other API Security protocols?

Unlike typical RESTful OAuth 2.0 API Security Protocols, T-Mobile has added a proprietary and unique Proof of Possession or PoP Token into the API security mix. A PoP Token must be generated anytime you wish to properly interact with either the OAuth 2.0 server or the API Resource server. Anytime AND everytime.

Some Other Important Things to Note

  • All T-Mobile APIs are based on RESTful architecture and are accessed via HTTPS at specific endpoints.
  • The base URL varies depending on the API that you are consuming.
  • The complete URL varies depending on the endpoint of the resource being accessed. Please see the individual API Product document for further details.
  • All APIs use JSON as their request and response payload format.

T-Mobile API Security Overview

T-Mobile uses an Open ID Connect (OIDC) aligned JWT (JSON Web Token) Access Token over OAuth 2.0 along with a proprietary Proof of Possession (PoP) Token to secure APIs. This overall mechanism is also referred to as TAAP, which is short for T-Mobile API Access Protocol.

The TAAP process works the following way:

  1. A Proof of Possession, or PoP Token, must be generated and signed using a client's Open SSL private key before each API request. The PoP Token is a T-Mobile proprietary JSON object who’s claims are defined by the TAAP process and signed into a JWT. The creation and signing process of a Proof of Possession (PoP) Token can be simplified using one of the libraries found here: https://github.com/tmobile/tmobile-api-security-lib.

    Some Proof of Possession (PoP) Tokens also require request body content which varies for each call. Learn more about the PoP Token process here.

  2. A public and private key must be generated using OpenSSL.
  3. The public key is given to T-Mobile while the private key is used to generate the Proof of Possession (PoP) JWT Token.
  4. Once the Proof of Possession (PoP) Token is generated, it is sent via a header API call using the key X-Authorization to the OAuth 2.0 server.

    Depending on the API, the client_id and client_secret must also be included

    If the Proof of Possession (PoP) Token, client_id, and client_secret are valid then the OAuth 2.0 server will return Access and ID JWT Tokens.

  5. The OAuth 2.0 Access and ID Tokens can then be used to call the functional resource API. The OAuth 2.0 Access Token is sent via the HTTP header key Authorization. The ID Token is sent via HTTP header key X-Auth-Originator. In addition, because the Proof of Possession (PoP) Token is not reusable and required for each API call, a new PoP Token must be generated then sent to the functional resource API, again, using X-Authorization as the key.
  6. Once these steps are complete the API resource can then return the desired response body via JSON.

T-Mobile API Access Protocol (TAAP) UML Flow Diagram

The below flow diagram demonstrates the above steps. They have been streamlined into 4 stages. Again, you must:

  1. Generate the Proof of Possession (PoP) Token for the OAuth 2.0 Server. The corresponding document to teach you how to do this is the Step 1: Generate PoP Token - OAuth 2.0 document.
  2. Use the OAuth 2.0 PoP Token to generate the OAuth 2.0 Access and ID Tokens. The corresponding document to teach you how to do this is the Step 2: Generate OAuth 2.0 Access and ID Tokens document.
  3. Generate the Proof of Possession (PoP) Token for the API Resource Server. The corresponding document to teach you how to do this is the Step 3: Generate PoP Token - API Resource document.
  4. Use the API Resource PoP Token, Access Token, and ID Token to request the API resource. The corresponding document to teach you how to do this is the Step 4: Functional Call to API Resource Server document.