OAuth 2.0 API
Introduction
The OAuth 2.0 Authentication Management API provides a safe and secure way for AT&T Wireless customers to access the AT&T Wireless network through a third-party app without the risk of compromising security.
This API ensures that secure, sensitive, and private AT&T Wireless customer-related details are not exposed to the third-party app. This API is based on an open framework recognized as providing a strong protection for users and apps.
This API provides you with a security model that enables you to obtain an OAuth authorization code and an OAuth access token. This API enables third-party apps to access the private resources of the customer without requiring the customer to provide credentials to the third-party app, such as a user name and password. By acquiring an OAuth authorization code, a customer authorizes an app to access a protected resource on behalf of the customer. The receipt of an OAuth access token enables an app to access a protected resource on behalf of a customer via the AT&T Wireless network.
Considerations
The RESTful OAuth 2.0 Authentication Management API provided by AT&T has the following considerations for you to keep in mind.
- The OAuth 2.0 Authentication Management API is the source of OAuth access tokens for use with all of the APIs provided by AT&T.
- You should specify an API scope in your request for all of the APIs that are included in your app account.
- The current implementation of this API sets the default value for the expires_in parameter to 172800 seconds, which signifies that the time-to-live for the OAuth access token is 2 days. The time-to-live for the OAuth refresh token is set to 7776000 seconds, which signifies that the time-to-live for the OAuth refresh token is 90 days.
Note: The actual time-to-live value may be different, so you should always check the value in the parameterexpires_in parameter.
- The current implementation of this API implements a Remember Me feature, which simplifies the process of granting consent by remembering the customer after the initial authorization. The Remember Me feature is enabled by default.
Get Access Token
The Get Access Token method obtains an OAuth access token which must be presented by the authorized app to make subsequent RESTful API requests to the API Gateway.
The OAuth access token is able to be obtained using any of the following workflows.
Your app must provide the App Key and App Secret that are specified in your app account in order to obtain an OAuth access token from the API Gateway.
This mechanism is used for an app that makes requests to APIs that require consent from the user.
You must send a Get User Authorization method request for an OAuth authorization code prior to requesting an OAuth access token.
The OAuth authorization code signifies the successful completion of an user consent authentication and must be exchanged for an OAuth access token.
This is the default configuration of the API Gateway for the following APIs.
- Address Book API (AAB)
- Device Capabilities API (DC)
- In-App Messaging API (IMMN, MIM)
- Using the App Key and App Secret
This mechanism is used for an app that makes requests to APIs that do not require user consent.
This is the default configuration of the API Gateway for the following APIs.
- Advertising API (ADS)
- MMS API (MMS)
- SMS API (SMS)
- Speech API (SPEECH, STTC, TTS)
- Using an OAuth Refresh Token
This mechanism is used to obtain a new OAuth access token using an OAuth refresh token.
The OAuth refresh token is used whether the original OAuth access token was requested using the OAuth authorization code or the App Key and App Secret.
This method does not require customer interaction even if the initial OAuth access token is obtained using an OAuth authorization code.
An OAuth refresh token is valid for 90 days, as indicated in the Considerations section.
Note: If a new OAuth access token is requested, then the original OAuth refresh token and associated OAuth access token are no longer valid and are no longer able to be used.
OAuth Scope
Scope: Not Applicable
Model: Not Applicable
Resource
POST https://api.att.com/oauth/v4/token
URL Encoded (authorization_code)
Request
POST https://api.att.com/oauth/v4/token HTTP/1.1 Host: api.att.com Content-Type: application/x-www-form-urlencoded Accept: application/json User-Agent: curl/7.37.0 Content-Length: 117
client_id=ABCDEF0123456789ABCDEF0123456789&client_secret=ABCDEF0123456789&grant_type=authorization_code&code=ABCDEF0123456789
Response
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Date: Wed, 30 Mar 2011 07:18:40 GMT
{
"access_token": "xyz123456789",
"expires_in": 172800,
"refresh_token": "abc987654321",
"token_type": "bearer"
}
URL Encoded (client_credentials)
Request
POST https://api.att.com/oauth/v4/token HTTP/1.1 Host: api.att.com Content-Type: application/x-www-form-urlencoded Accept: application/json User-Agent: curl/7.37.0 Content-Length: 118
client_id=ABCDEF0123456789ABCDEF0123456789&client_secret=ABCDEF0123456789&grant_type=client_credentials&scope=ADS
Response
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Date: Wed, 30 Mar 2011 07:18:40 GMT
{
"access_token": "xyz123456789",
"expires_in": 172800,
"refresh_token": "abc987654321",
"token_type": "bearer"
}
URL Encoded (refresh token)
Request
POST https://api.att.com/oauth/v4/token HTTP/1.1 Host: api.att.com Content-Type: application/x-www-form-urlencoded Accept: application/json User-Agent: curl/7.37.0 Content-Length: 162
client_id=ABCDEF0123456789ABCDEF0123456789&client_secret=ABCDEF0123456789&grant_type=refresh_token&refresh_token=ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789
Response
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Date: Wed, 30 Mar 2011 07:18:40 GMT
{
"access_token": "xyz123456789",
"expires_in": 172800,
"refresh_token": "abc987654321",
"token_type": "bearer"
}
Accept
String
Header
Specifies the format of the body for the response. The acceptable values for this parameter are:
- application/json
The default value is application/json.
Note: For this method, this parameter specifies how the entity should be represented in case of an error.
This parameter is for setting the format of an error message. If there is no error, then the representation matches the form of the actual content.
client_id
String
Body
Specifies a key that identifies the user's app.
Note: This parameter value is the App Key that is assigned to the app account on the AT&T Developer Program website.
client_secret
String
Body
Specifies a secret key associated with the user's app.
Note: This parameter value is the App Secret that is assigned to the app account on the AT&T Developer Program website.
code
String
Body
Specifies the OAuth authorization code that is returned by the API Gateway when a user authorizes the app account to consume APIs on the user's behalf.
Note: This parameter is required only when the grant_type parameter is set to authorization_code.
Content-Type
String
Header
Specifies the type of content.
The only acceptable value for this parameter is:
- application/x-www-form-urlencoded
grant_type
String
Body
Specifies the grant type used to obtain the OAuth access token.
The acceptable values for this parameter are:
- authorization_code : The code value returned by the Get User Authorization method is used.
- client_credentials : The App Key and App Secret are used.
- refresh_token : The refresh_token from a previous response to this method request is used.
refresh_token
String
Body
Specifies the OAuth refresh token that is returned by the API Gateway during a previous response to this method request.
This parameter value is stored and used to obtain a new OAuth access token when the initial OAuth access token expires.
Note: This parameter is required in the request only when the grant_type parameter is set to refresh_token.
scope
String
Header
Specifies the APIs associated with your app account to which the app is requesting access.
The format for this parameter value is a comma delimited list.
The acceptable values for this parameter are:
- ADS : Advertising API.
- MMS : MMS API.
- SMS : SMS API.
- SPEECH : Speech API - Speech To Text method.
- STTC : Speech API - Speech To Text Custom method.
- TTS : Speech API - Text To Speech method.
Note: This parameter is only required when the grant_type parameter is set to client_credentials.
Example: scope=ADS
Example: scope=SPEECH,STTC,TTS
Example: scope=MMS,SMS,SPEECH,STTC,TTS
Get User Authorization
The Get User Authorization method obtains an OAuth authorization code. This method triggers the user consent flow, which authenticates the user and captures the user's consent given to the app. The user is informed of the one or more API scopes that you specified in your app account. The successful response provides an OAuth authorization code that may be exchanged for an OAuth access token with permission to access the specified APIs. The request and response flow for this method, including the user content flow, is the following.
Sorry! Your session has expired.