Site Optimized for Chrome and Firefox
Site Optimized for Chrome and Firefox
Site Optimized for Chrome and Firefox
The MMS API was deprecated on July 29, 2015. Get more information about our supported APIs.
x
/apis/sms-mms /apis/mms/docs
Site Optimized for Chrome and Firefox
The Device Capabilities API was deprecated on July 29, 2015. Get more information about our supported APIs.
x
/apis/device-capabilities /apis/device-capabilities/docs
Active: AT&T version 4.
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 expires_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.
Provisioning

The RESTful OAuth 2.0 Authentication Management API provided by AT&T requires that you provision your app as follows.

You must register an app account on the AT&T Developer Program website in order to utilize this API.

Resources
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.

  • Using the OAuth Authorization Code

    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
  • copy
    POST https://api.att.com/oauth/v4/token 
Request and Response Examples

Request

copy
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

copy
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"
} 

Request

copy
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

copy
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"
} 

Request

copy
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

copy
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"
} 
Request Parameters
Parameter
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 Body

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

Response Parameters
Parameter
access_token String Body

Specifies a token that is used to request access to an API.

If the grant_type parameter in the original request is set to authorization_code, then the value of this parameter is used by the app to make a request on behalf of the user to the API Gateway.

If the grant_type parameter in the original request is set to client_credentials, then the value of this parameter is used by app to make a request to the API Gateway.

expires_in Integer Body

Specifies the number of seconds before the current OAuth access token expires.

Note: If the parameter value is set to zero ( 0 ), then the lifespan of the OAuth access token is non-expiring or infinite.

refresh_token String Body

Specifies the token that is used to obtain a new OAuth access token after the initial OAuth access token that is returned in a previous response expires.

Note: The original OAuth refresh token is no longer valid after it is used to obtain a new OAuth access token.

Note: A new OAuth refresh token is provided with the new OAuth access token.

token_type String Body

Specifies the type for the new OAuth access token.

The only acceptable value for this parameter is:

  • bearer
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.

  1. The app initiates the flow by directing the user's user-agent to the authorization endpoint.
  2. The authorization server authenticates the user via the user-agent and establishes the user's identity and whether the user grants or denies the your access request.
  3. Assuming the user grants access, the authorization server redirects the user-agent back to the app using the redirection URI provided earlier. The redirection URI includes the OAuth access token in the URI fragment.
  • OAuth Scope
  • Scope: Not Applicable

  • Model: Not Applicable

  • Resource
  • copy
    GET https://api.att.com/oauth/v4/authorize 
Request and Response Examples

Request

copy
GET https://att.api.att.com/oauth/v4/authorize?client_id=ABCDEF0123456789ABCDEF0123456789&scope=IMMN,MIM&redirect_uri=https://your.oauth.redirect.uri HTTP/1.1
Host: api.att.com 

Response

copy
HTTP/1.1 302 Found
https://your.oauth.redirect.uri?code=01234xyz56789abc== 
Request Parameters
Parameter
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 will match the form of the actual content.

client_id String Query Parameter

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.

scope String Query Parameter

Specifies the APIs associated with your app account to request the user's consent.

The format for this parameter value is a comma delimited list.

The acceptable values for this parameter are:

  • AAB : Address Book API.
  • DC : Device Capabilities API.
  • IMMN : In-App Messaging API - Send Message method.
  • MIM : In-App Messaging API - Create Message Index, Delete Message, Delete Messages, Get Message, Get Message Content, Get Message Index Info, Get Message List, Get Messages Delta, Get Notification Connection Details, Update Message, and Update Messages methods.

Note: This parameter is required only when the grant_type parameter is set to client_credentials.

Example: scope=AAB,IMMN,MIM

redirect_uri String Query Parameter

Specifies the URI where the user's Web browser will be redirected following completion of the authorization process.

This parameter value may either be an exact match to the OAuth Redirect URI in the app account on the AT&T Developer Program website or be an extension of that value.

Note: If this parameter is not present in the request, then the API Gateway uses the value of the OAuth redirect URI that is provided by the developer in the app account.

Note: If this parameter is present in the request, then this parameter value is validated to ensure that the value of the redirect_uri parameter does not differ from what was provided in the app account.

Note: The value of redirect_uri may extend the OAuth Redirect URI value by appending additional path elements or query parameters.

custom_param String Query Parameter

Specifies the comma-separated list of parameters that control the behavior of the authorization flow.

The acceptable values for this parameter are:

  • bypass_onnetwork_auth : Forces the off network user authorization flow. This means that the authorization flow will appear to the user as if not on the AT&T Wireless network.
  • suppress_landing_page : Suppresses the display of the switch user page during a Get User Authorization method request with a Remember Me cookie present on the mobile device.

Note: If conditions do not permit the on network flow, then the inclusion of this parameter has no effect.

Note: If bypass_onnetwork_auth is specified, then the system behavior is to redirect the user agent through the off network flow where the user may enter a MSISDN and PIN or an Access ID and password combination in order to authenticate.

Note: If bypass_onnetwork_auth is specified and the Remember Me cookie exists and is valid for the instance of the app, then the Remember Me flow must take precedence.

Note: If suppress_landing_page is specified and the Remember Me cookie is not present, then this parameter has no impact.

Example: custom_param:bypass_onnetwork_auth,suppress_landing_page

Response Parameters
Parameter
code String Query Parameter

Specifies the OAuth authorization code that represents the successfully processed user consent.

Note: The Get Access Token method uses this parameter value to retrieve an OAuth access token.

Revoke Token

The Revoke Token method revokes an OAuth access token or OAuth refresh token.

  • OAuth Scope
  • Scope: Not Applicable

  • Model: Not Applicable

  • Resource
  • copy
    https://api.att.com/oauth/v4/revoke 
Request and Response Examples

Request

copy
POST https://api.att.com/oauth/v4/revoke  HTTP/1.1
Host: api.att.com
Content-Type: application/x-www-form-urlencoded

client_id=ABCDEF0123456789ABCDEF0123456789&client_secret=ABCDEF0123456789&token=xyz123456789&token_type_hint=access_token 

Response

copy
HTTP/1.1 200 OK 

Request

copy
POST https://api.att.com/oauth/v4/revoke  HTTP/1.1
Host: api.att.com
Content-Type: application/x-www-form-urlencoded

client_id=ABCDEF0123456789ABCDEF0123456789&client_secret=ABCDEF0123456789&token=abc987654321&token_type_hint=refresh_token 

Response

copy
HTTP/1.1 200 OK 
Request Parameters
Parameter
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.

Content-Type String Header

Specifies the type of content.

The only acceptable value for this parameter is:

  • application/x-www-form-urlencoded
token String Body

Specifies the OAuth access token or OAuth refresh token issued by the API Gateway.

token_type_hint String Body

Specifies a hint about the type of the token submitted for revocation.

The acceptable values for this parameter are:

  • access_token : An OAuth access token is being revoked.
  • refresh_token : An OAuth refresh token is being revoked.