Step 2: Generate OAuth 2.0 Access and ID Tokens
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.
- https://naas.t-mobile.com/oauth2/v2/tokens
- 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