Step 2: Generate OAuth 2.0 Access and ID Tokens

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

Introduction

This document guides the reader on how to create a T-Mobile OAuth 2.0 Access and ID Token.

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

Prerequisites

A DevEdge Account. If you do not have a DevEdge account please create one now.
You completed all the steps in the Step 1: Generate PoP Token - OAuth 2.0.
A computer with Postman installed on it.
A computer with a web browser.
Internet access.

Why would l want to implement the steps in this document?

In order to access T-Mobile's APIs you must be able to successfully authenticate through T-Mobile's OAuth 2.0 security.

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.

Generate an Access and ID Token

Below is a cURL request for one of T-Mobile's OAuth 2.0 Servers.

curl --location --request POST '<FQDN>/oauth2/v2/tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <BASE64_ENCODED_CLIENT_ID:CLIENT_SECRET>' \
--header 'X-Authorization: <OAUTH_2_POP_TOKEN_ARGUMENT>' \
--data-raw ''

Note the following about the cURL request:

Parameter	Request Type	Description	Required
Authorization	Header	A "Basic" token made from a Base64 encoding of your client_id and client_secret. Please read the document Step 1: Generate PoP Token - OAuth 2.0 to learn more.	Yes
Content-Type	Header	Defines the content type that is being sent through the body. This must be set to "application/json".	Yes
X-Authorization	Header	A T-Mobile specific token called the Proof of Possession (PoP) Token. Learn more about the PoP token here.	Yes

Replace the X-Authorization value with the PoP Token you created in the Step 1: Generate PoP Token - OAuth 2.0.

The PoP Token only lasts for 60 seconds. In addition, the PoP Token only works for one hop.
Obtain your client_id and client_secret from the subscription page on DevEdge.
Replace the Authorization value with your "Basic" Base64 CLIENT_ID:CLIENT_SECRET encoded argument in your cURL call.

An example of what your cURL request might look like can be found below:

BEFORE:

curl --location --request POST '<FQDN>/oauth2/v2/tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <BASE64_ENCODED_CLIENT_ID:CLIENT_SECRET>' \
--header 'X-Authorization: <OAUTH_2_POP_TOKEN_ARGUMENT>' \
--data-raw ''

AFTER:

curl --location --request POST 'https://naas.t-mobile.com/oauth2/v2/tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MTIzOmFiYw==' \
--header 'X-Authorization: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlZHRzIjoiLVV2VnlQVlpwT00tVWZWYjUwWk8tX2JBV2dSVXVzeVRlU0w0cDdTcExKTSIsInYiOiIxIiwiZXhwIjoxNjYwNjY1NjY0LCJlaHRzIjoiQ29udGVudC1UeXBlO0F1dGhvcml6YXRpb247dXJpO2h0dHAtbWV0aG9kO2JvZHkiLCJpYXQiOjE2NjA2NjU1NDQsImp0aSI6IjllMmI1MjYwLTk0MjQtYzIyOC01NWE5LTkzNTcyZmUxMjVhYSJ9.sL1JYALoUaZMt_ZoenN9wKwREYTpR3Gf5MAGCj2LqIwTWTNVGDsPMvMRvlAHyOQDtgnJqQYkAeCKFL9Gl-UAy2i5j1EbnCDTOT1TizxqEL0hpYatF-swtbPKuso51kRv_97jCCA0FqYr9YBRlYJvPi1gQ60Hk39SaNdJoBO5hQuilCLBxccDJ-pfMNKvEmYdFBzoihe2ELUtVXgxcJjOKzPX4S047sru37gg_ygaNAQFxN-NfS3LoxCn-AUjLmWsJf0aI_s23hVLG9BxYknrdEYBPiZO-N8EqXYnpa1WqY4TyuDdLPgwCBpnTpBtA8qp2PGaYRpG6tGD2x38LpXhRw' \
--data-raw ''

Import your cURL request into Postman.
Send the request.

The OAuth 2.0 response body looks like the below:

{
    "id_token": "",
    "access_token": "",
    "expires_in": "3599",
    "scope": "",
    "status": "approved"
}

An example, with data, can be seen below:

{
    "id_token": "eyJraWQiOiJmYjk3ZGQxZi0xMDUzLTRiZGEtYjQ2OC1lZjU3ODdmZTA1MTMiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ0bW9uLU9nUE5tVDVoVVE1OHpOWXlZYktueHA5QTZKNktrcUg2IiwiYXVkIjoidG1vbi1PZ1BObVQ1aFVRNTh6Tll5WWJLbnhwOUE2SjZLa3FINiIsImlzcyI6Imh0dHBzOlwvXC9hcGlzLnQtbW9iaWxlLmNvbVwvb2F1dGgyXC92MSIsImV4cCI6MTY2NzYwODMxMCwiaWF0IjoxNjY3NjA0NzEwLCJqdGkiOiJhMDU1MDBlZS1jYTc3LTQ0ZDAtYTBlMC1hMjU4NTBiMzk3ZjkifQ.XTkkgu-ok86Jq1m1lJ3qMRxkvb4JbQNx8gBmaSosPzds_gHkeKydaKjGDDIKA9iFYm3i4tqhwmznUwjT3aDmwKGMoxI9PjXMTemvGQ3fh4HKKBmVni8ZRj9zxA3C9E3nNfhwOWwXXbTsdF3DROnxCFOGj8x9k35nSXm9avDU-20CToi8JJHJeu7ZogsFTu2l6aeO2QZpEVURFLHfY7uwjYl7S6h8Y1M-XJRQnF9NcaJzWKPKYr8eLLbQCwMkLSbgjtotNQdJ1TbrUa9uzL0NzsJcjVUmNdpDOU0Zk55I2GtebMZQ_QN2kTNVL1igyBCKfmy9HYujZguZlrhtewYEEg",
    "access_token": "eyJraWQiOiJmYjk3ZGQxZi0xMDUzLTRiZGEtYjQ2OC1lZjU3ODdmZTA1MTMiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ0bW9uLU9nUE5tVDVoVVE1OHpOWXlZYktueHA5QTZKNktrcUg2IiwiYXVkIjoidG1vbi1PZ1BObVQ1aFVRNTh6Tll5WWJLbnhwOUE2SjZLa3FINiIsImlzcyI6Imh0dHBzOlwvXC9hcGlzLnQtbW9iaWxlLmNvbVwvb2F1dGgyXC92MSIsImV4cCI6MTY2NzYwODMxMCwiaWF0IjoxNjY3NjA0NzEwLCJqdGkiOiJhMDU1MDBlZS1jYTc3LTQ0ZDAtYTBlMC1hMjU4NTBiMzk3ZjkifQ.XTkkgu-ok86Jq1m1lJ3qMRxkvb4JbQNx8gBmaSosPzds_gHkeKydaKjGDDIKA9iFYm3i4tqhwmznUwjT3aDmwKGMoxI9PjXMTemvGQ3fh4HKKBmVni8ZRj9zxA3C9E3nNfhwOWwXXbTsdF3DROnxCFOGj8x9k35nSXm9avDU-20CToi8JJHJeu7ZogsFTu2l6aeO2QZpEVURFLHfY7uwjYl7S6h8Y1M-XJRQnF9NcaJzWKPKYr8eLLbQCwMkLSbgjtotNQdJ1TbrUa9uzL0NzsJcjVUmNdpDOU0Zk55I2GtebMZQ_QN2kTNVL1igyBCKfmy9HYujZguZlrhtewYEEg",
    "expires_in": "3599",
    "scope": "",
    "status": "approved"
}

Copy the access_token argument then move on to the Step 3: Generate PoP Token - API Resource.

Troubleshooting

Issue 1 - I am receiving errors when sending a request to the OAuth 2.0. 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.

FAQ

Question 1 - Do all of T-Mobile's APIs use the same OAuth 2.0 authentication server?
Answer 1 - No. There are two OAuth 2.0 authentication servers.
1. https://naas.t-mobile.com/oauth2/v2/tokens
2. https://api.t-mobile.com/oauth2/v6/tokens

Question 2 - Which APIs use what OAuth 2.0 server?

Answer 2 - Please see the chart below to understand which API uses which server.

API	OAuth 2.0 Server Used	Where can I find my Client ID and Client Secret
Call Verification	https://api.t-mobile.com/oauth2/v6/tokens	https://docs.devedge.t-mobile.com/account-settings/apiKeys
Connectivity	https://naas.t-mobile.com/oauth2/v2/tokens	https://devedge.t-mobile.com/dashboard/subscription
Fraud Prevention	https://api.t-mobile.com/oauth2/v6/tokens	https://docs.devedge.t-mobile.com/account-settings/apiKeys
Location	https://naas.t-mobile.com/oauth2/v2/tokens	https://devedge.t-mobile.com/dashboard/subscription
SMS Notification	https://naas.t-mobile.com/oauth2/v2/tokens	https://devedge.t-mobile.com/dashboard/subscription

Question 3 - Is there a difference between the cURL calls for the https://naas.t-mobile.com/oauth2/v2/tokens versus the https://api.t-mobile.com/oauth2/v6/tokens.

Answer 3 - Yes there is. The above example demonstrated how to make a request to the https://naas.t-mobile.com/oauth2/v2/tokens server. The call to the https://api.t-mobile.com/oauth2/v6/tokens contains a body request and looks like the following. Everything else remains the same.

curl --location --request POST 'https://api.t-mobile.com/oauth2/v6/tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <CLIENT_ID:CLIENT_SECRET BASE64 ENCODED>' \
--header 'x-authorization: <POP_TOKEN_ARGUMENT>' \
--data-raw '{ "client_id": "<CLIENT_ID_ARGUMENT>", "client_secret" : "<CLIENT_SECRET_ARGUMENT>", "scope" : "response_mode", "grant-type": "client_credentials" }'

Question 4 - Do you have a description of the https://api.t-mobile.com/oauth2/v6/tokens cURL request body?

Answer 4 - Yes, please see the chart below.

Parameter	Request Type	Description	Required
Authorization	Header	A "Basic" token made from a Base64 encoding of your client_id and client_secret. Please read the document Step 1: Generate PoP Token - OAuth 2.0 to learn more.	Yes
Content-Type	Header	Defines the content type that is being sent through the body. This must be set to "application/json".	Yes
X-Authorization	Header	A T-Mobile specific token called the Proof of Possession (PoP) Token. Learn more about the PoP token here.	Yes
storeId	Body	Optional data that can be added to the body request if desired. Adds a store identification number to the request.	No
dealerCode	Body	Optional data that can be added to the body request if desired. Adds a dealer code to the request.	No
client_id	Body	Your OAuth 2.0 Client ID found on either the API key page.	Yes
client_secret	Body	Your OAuth 2.0 Client Secret found on either the API key page.	Yes
scope	Body	The value for this parameter must be set to "response_mode".	Yes
grant-type	Body	The value for this parameter must be set to "client_credentials".	Yes