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

Token Overview

Home / Portfolio / Content / Technical Writing / API Security / Token Overview

Introduction

This document presents an overview of the different tokens used in the T-Mobile API security process, also known as T-Mobile API Access Protocol (TAAP).

Some Background

T-Mobile uses a proprietary security authentication mechanism called TAAP which is short for T-Mobile API Access Protocol.

The T-Mobile API Access Protocol (TAAP) is designed to address several limitations and security issues with previous approaches of two-way SSL or OAuth 2.0 opaque bearer tokens. TAAP leverages OAuth 2.0 but also incorporates additional aspects of the below technologies to achieve API security:

  1. JSON Web Tokens (JWT)
    • A description can be found here.
  2. Digital signature using an asymmetric key pair
    • The JWT's token integrity is established using a digital signature cryptography mechanism or RSA (Rivest–Shamir–Adleman) algorithm.
    • T-Mobile recommends that you learn more about the OpenSSL toolkit here.
  3. OpenID Connect 1.0 (OIDC)
    • Access Token
    • Identity (ID) Token
    • A description can be found here.
  4. Proof of Possession (PoP) Token (a T-Mobile proprietary token format)
    • Learn more about the PoP Token here.

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. Proof of Possession (PoP) token essentially acts as digitally signature of the entire API request. A T-Mobile API Access Protocol (TAAP) compliant request to the resource server (REST API) allows the resource to verify not only that the client has been authenticated by the authorization server (using Access/ID token) but also whether the request has originated from the client who possesses the signing key (using a PoP Token).

Token Description

Token Type

Token Description

HTTP Header

Token Validity

Proof of Possession (PoP) Token

  • The PoP Token is a T-Mobile proprietary JSON object who's format is defined by the TAAP (T-Mobile API Access Protocol) specification and must be a signed JWT. The creation and signing process of a PoP (Proof of Possession) Token can be simplified using one of the libraries found here: https://github.com/tmobile/tmobile-api-security-lib/tree/master/poptoken-lib/poptoken-builder

  • Learn how to generate the OAuth 2.0 PoP Token here.

  • This token must be generated first in order to call any API, including the OAuth 2.0 server and API Resource Server.

  • The Proof of Possession (PoP) Token acts as second identity factor of the client, using a digital signature.

  • Is passed in the HTTP header key via the X-Authorizationvariable.

X-Authorization

  • The Proof of Possession (PoP) token is valid for only one hop and one API request.

  • Is only valid for 60 seconds.

OAuth 2.0 Access Token

  • The OAuth 2.0 Access Token is generated by the T-Mobile OAuth 2.0 servers.

  • Access & ID JWT tokens are returned together.

  • Is passed in the HTTP header key via the Authorization variable as a Bearer token in the API request to the resource server.

  • Is also passed in the HTTP header key via the Authorization variable as a Basic token in the OAuth 2.0 request.

Authorization

  • The OAuth 2.0 Access Token is valid only for a specific client.

  • Is only valid for 3600 seconds or one hour.

  • Contact us if a custom expiration is required.

OAuth 2.0 ID Token

  • The ID token is generated along with the Access Token by the T-Mobile OAuth 2.0 servers.

  • The ID Token holds basic identity information of the application user/system.

  • The ID Token is the primary source of reference for entitlement data and used in domain authorization (AuthZ) by resource servers.

  • Is passed in the HTTP header key via the X-Auth-Originator in the API request to the resource server.

X-Auth-Originator

  • The ID Token is valid across multiple API resource domains and used for Authorization decisions.

  • Is valid for 3600 seconds or one hour.

  • Unlike the Access Token, do not prefix Bearer when sending.