The FirstNet Call Management API allows a third party application to create and manage calls between mobile phones. The API provides functions to application developers for the following:

1. Establish a call session between calling participant and called participant
2. Obtain information of a call session
3. Terminate a call session

Onboarding Prerequisites:

1. The developer must onboard to the AT&T Multi-Services Proxy (MSP) platform.
2. The developer’s app must be listed in the App Catalog.
3. The developer must onboard to the FirstNet Mobile SSO platform and, for native mobile application development, the developer must also get access to the Mobile SSO libraries.
4. The developer of a browser-based application must onboard to the Halo platform.

Apps utilizing the FirstNet service will need to be provisioned (refer to the Prerequisites section) and will need to supply an OAuth access token with all API requests.

To retrieve an OAuth access token, multiple authentication and authorization methods are supported with Client Credentials and FirstNet SSO credentials (OAuth model - Password Grant).

To get FirstNet SSO credentials (OAuth model - password grant i.e. authorization from an end user) the developer must use the HALO platform in conjunction with the Mobile Key flow for a native app.

The App will first call the OAuth 2.0 Authorization API to get the OAuth access tokens.

The OAuth 2.0 Authorization API provides a highly secure way for AT&T wireless customers to access the AT&T wireless network through a third-party app with less risk of compromising security. This API helps ensure that sensitive AT&T wireless customer-related details are not exposed to the third-party app.

Note: The OAuth 2.0 Authorization API provided by AT&T has the following considerations for you to keep in mind:

• You should specify an API scope in your request that includes all of the APIs that you plan to use.

Each of the APIs in the FirstNet service require specific scopes assigned to the access tokens use in the calls to those APIs. These scopes are as follows:

The purpose of the Get Access Token method is to obtain an OAuth access token that can then be presented by the authorized application to make subsequent requests to AT&T APIs.
The app must provide the App Key and App Secret pair for either the Sandbox or Production instance of the app account in order to obtain an OAuth access token.

The OAuth access token can be obtained in the following ways:

• Using the Password Grant: This mechanism is used directly as an authorization grant to obtain an access token. Instead of a password, this grant type uses a HALO authentication token. This mechanism can only be used if at least one of the requested scopes uses the password grant_type.
• Using the Client Credentials: Using the Client Credentials: This mechanism is used when the application requires no customer authorization and consent capture.
• Using a Refresh Token: The refresh token mechanism can be used to obtain a new OAuth access token. The access token is valid until the time indicated in the expires_in parameter is reached. When a token is about to expire, an application should refresh it using the refresh token. Upon obtaining a new OAuth access token, the original refresh token and OAuth access token are invalidated and can no longer be used.
  Note: The refresh token value is not returned for the Password Grant type.

Grant_Type: Client Credentials

Call flow

Request - Client credentials grant type

The following example shows how to get an access token using the Password Grant credential. The value of the Accept parameter specifies that the response from the API Gateway should be in JSON.

POST /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=client_credentials&scope=FIRSTNET:CALLMGMT

Request - Refresh token (valid only for Client Credentials grant type)

The following example demonstrates how to get an access token based on a previously acquired access token. The value of the Accept parameter specifies that the response from the API Gateway should be in JSON.

POST /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=ABCDEF012 3456789&grant_type=refresh_token&refresh_token=ABCDEF0123456789ABC DEF0123456789ABCDEF0123456789

Response (Client credentials grant type)

The following example shows a Get Access Token Response in JSON format.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Date: Wed, 30 Mar 2011 07:18:40 GMT
{
"access_token": "b305a68014c81ddd6e9dcf172d2a1064",
"expires_in": "7200",
"refresh_token": "d6439f42285acc03566709c4eea4fd49bc189b72",
"token_type": "bearer"

Grant_Type: FirstNet SSO credentials (OAuth model – Password Grant)

Prerequisites: (refer to section 2 Provisioning and Authorization)

• The application developer has onboarded to the HALO platform and successfully generated a HALO token via the MobileKey SDK.
• The HALO token will work for valid FirstNet user credentials only.
• Once the 3rd party application gets the HALO token, the developer hosted server must use the following API to get the access token.

Request - Password Grant

The following example shows how to get an access token using the Password grant. The value of the Accept parameter specifies that the response from the API Gateway should be in JSON.

POST /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=password&username={CTN/Mobile Number}&password={HALO_TOKEN}&scope

Response

The following example shows a Get Access Token Response in JSON format.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Date: Wed, 30 Mar 2011 07:18:40 GMT
{
"access_token": "b305a68014c81ddd6e9dcf172d2a1064",
"expires_in": "7200",
"refresh_token": "d6439f42285acc03566709c4eea4fd49bc189b72",
"token_type": "bearer"
}

CallParticipantTerminationCause Enumeration

Valid Values
CallParticipantNoAnswer
CallParticipantBusy
CallParticipantNotReachable
CallParticipantHangup
CallParticipantAborted

CallParticipantStatus Enumeration

Valid Values
CallParticipantInitial
CallParticipantConnected
CallParticipantTerminated

Functional Behavior

This operation is used to initiate a call session between 2 participants (source party and destination party). Once the API has executed, the source participant’s device (phone) rings. When the source participant answers the phone, the destination participant’s device will ring.

Call Flow

Request - Example (Client Credentials)

POST /firstnetCallManagement/v1/callSessions HTTP 1.1
Host: api.att.com
Authorization: Bearer Y3BzOmNwczEyMw ==
Content-Type: application/json
Accept: application/json
{
  "callSession": {
    "clientCorrelator": "123456756",
    "participant": [
      {
        "participantAddress": "sip:+19876543210@firstnet.com",
        "participantName": "Source Party"
      },
      {
        "participantAddress": "sip:+19876543210@firstnet.com",
        "participantName": "Destination Party"
      }
    ]
  }
}

Request - Example (Password Grant)

Note: the first source participantAddress is not required and will be retrieved from the access_token.

POST /firstnetCallManagement/v1/callSessions HTTP 1.1
Host: api.att.com
Authorization: Bearer Y3BzOmNwczEyMw ==
Content-Type: application/json
Accept: application/json
{
  "callSession": {
    "clientCorrelator": "123456756",
    "participant": [
      {
        "participantName": "Source Party"
      },
      {
        "participantAddress": "sip:+19876543210@firstnet.com",
        "participantName": "Destination Party"
      }
    ]
  }
}

Output Parameters

Response - Example

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 624
Location: https://api.att.com/firstnetCallManagement/v1/callSessions/callsession1234001
Date: Thu, 04 Jun 2010 02:51:59 GMT
{
  "callSession": {
    "clientCorrelator": "123456756",
    "participant": [
      {
        "participantAddress": "sip:+19876543210@firstnet.com",
        "participantName": "Source Party",
        "participantStatus": "CallParticipantInitial"
      },
      {
        "participantAddress": "sip:+19876543210@firstnet.com",
        "participantName": "Destination Party",
        "participantStatus": "CallParticipantInitial"
      }
    ],
    "terminated": false
  }
}

Response - HTTP Status Codes

Service Exceptions

Functional Behavior

This operation retrieves the information of an existing call session.

Call flow

Input Parameters

Request - Example (Client credentials grant)

GET /firstNetCallManagement/v1/callSessions/callsession1234001 HTTP/1.1
Host: api.att.com
authorization: Bearer abcdef12345678
accept: application/json
x-att-msisdn: {phone number}

Request - Example (FirstNet SSO Credentials)

GET /firstNetCallManagement/v1/callSessions/callsession1234001 HTTP/1.1
Host: api.att.com
authorization: Bearer abcdef12345678
accept: application/json

Output Parameters

Response - Example

HTTP/1.1 200 Ok
Content-Type: application/json
Content-Length: 624
Date: Thu, 04 Jun 2010 02:51:59 GMT
{
  "callSession": {
    "clientCorrelator": "123456756",
    "participant": [
      {
        "participantAddress": "sip:+19876543210@firstnet.att.net.com",
        "participantName": "Source Party",
        "participantStatus": "CallParticipantInitial"
      },
      {
        "participantAddress": "sip:+19876543210@firstnet.att.net.com",
        "participantName": "Destination Party",
        "participantStatus": "CallParticipantInitial"
      }
    ],
    "terminated": false
}

Response - HTTP Status Codes

Service Exceptions

Functional Behavior

This operation terminates an existing call session.

Call flow

Input Parameters

Request - Example (Client Credentials)

DELETE /firstNetCallManagement/v1/callSessions/callsession1234001 HTTP/1.1
Host: api.att.com
authorization: Bearer abcdef12345678
accept: application/json
x-att-msisdn: {phone number}

Request - Example (FirstNet SSO Credentials)

DELETE /firstNetCallManagement/v1/callSessions/callsession1234001 HTTP/1.1
Host: api.att.com
authorization: Bearer abcdef12345678
accept: application/json

Output Parameters

Response - Example

HTTP/1.1 200 Ok
Content-Type: application/json
Content-Length: 624
Date: Thu, 04 Jun 2010 02:51:59 GMT
{
  "callSession": {
    "clientCorrelator": "123456756",
    "participant": [
      {
     "duration" : 30,
        "participantAddress": "sip:+19876543210@firstnet.att.net.com",
        "participantName": "Source Party",
        "participantStatus": "CallParticipantInitial",
         "startTime" : "2018-11-01T18:39:09.267Z",
        "terminationCause" : "CallParticipantAborted"
      },
      {
     "duration" : 28,
        "participantAddress": "sip:+19876543210@firstnet.att.net.com",
        "participantName": "Destination Party",
        "participantStatus": "CallParticipantInitial",
        "startTime" : "2018-11-01T18:39:09.267Z",
        "terminationCause" : "CallParticipantAborted"
      }
    ],
    "terminated": "true"
}

Response - HTTP Status Codes

Service Exceptions

RESTful Webservices Exceptions

Two types of RESTful exceptions are supported:

• Service Exceptions: These exceptions occur when a service is unable to process a request and retrying the request will result in a consistent failure. For example, if an application provides invalid input.
• Policy Exceptions: These exceptions occur when a policy criterion has not been met. For example, if (N+1)th request arrives when an application's service level agreement only allows for N transactions per second.

The error information will be in the entity body as well as the entity body. This serves as a migration from having the errors in the body to the errors in the header, so both will be supported until a date is determined to discontinue the errors in the body.

Both service and policy exceptions contain the following elements:

Sample exception responses are provided below:

SVC0001 Exception - JSON Body:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 115
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errormessageId: SVC0001
x-att-errortext: A service error occurred. Error code is %1
x-att-errorvariables: error message from system
x-att-errorType: service
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=SVC0001
{
    "requestError": {
        "serviceException": {
            "messageId": "SVC0001",
            "text": "A service error occurred. Error code is %1",
            "variables": "error message from system"
        }
    }
}

SVC0002 Exception - JSON Body:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 115
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errormessageId: SVC0002
x-att-errortext: Invalid input value for message part %1
x-att-errorvariables: count
x-att-errorType: service
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=SVC0002
{
    "requestError": {
        "serviceException": {
            "messageId": "SVC0002",
            "text": "Invalid input value for message part %1",
            "variables": "count"
        }
    }
}

SVC0003 Exception - JSON Body:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 11SVC0001
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errormessageId: SVC0003
x-att-errortext: Invalid input value for message part %1, valid values are %2
x-att-errorvariables: size,small,medium,large
x-att-errorType: service
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=SVC0003
{
    "requestError": {
        "serviceException": {
            "messageId": "SVC0003",
            "text": "Invalid input value for message part %1, valid values are %2",
            "variables": "size,small,medium,large"
        }
    }
}

SVC1002 Exception - JSON Body:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 115
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errormessageId: SVC1002
x-att-errortext: Missing mandatory parameter %1
x-att-errorvariables: count
x-att-errorType: service
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=SVC1002
{
    "requestError": {
        "serviceException": {
            "messageId": "SVC1002",
            "text": "Missing mandatory parameter %1",
            "variables": "count"
        }
    }
}

SVC1002 Exception (When Authorization parameter is missing) - JSON Body:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: 115
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errormessageId: SVC1002
x-att-errortext: Missing mandatory parameter %1
x-att-errorvariables: authorization
x-att-errorType: service
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=SVC1002
{
    "requestError": {
        "serviceException": {
            "messageId": "SVC1002",
            "text": "Missing mandatory parameter %1",
            "variables": "authorization"
        }
    }
}

URI Location Not Found (Due to a parameter as an URI path element)

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 186
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errormessageId: SVC1002
x-att-errortext: Missing mandatory parameter %1
x-att-errorvariables: someId
x-att-errorType: service
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=SVC1002
{
    "requestError": {
        "serviceException": {
            "messageId": "SVC1002",
            "text": "Missing mandatory parameter %1",
            "variables": "someId"
        }
    }
}

POL0001 Exception - JSON Body:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: 115
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errormessageId: POL0001
x-att-errortext: A policy error occurred. Error code is %1
x-att-errorvariables: invalid accesstoken
x-att-errorType: policy
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=POL0001
{
    "requestError": {
        "PolicyException": {
            "messageId": "POL0001",
            "text": "A policy error occurred. Error code is %1",
            "variables": "invalid accesstoken"
        }
    }
}

HTTP 503 - with retry:
There may be situations when the server becomes overloaded due to aggregated TPS limits being reached. In this can a HTTP 503 will be returned with a Retry-After HTTP header giving the number of seconds to wait to retry the request.

HTTP/1.0 503 Service Unavailable
Retry-After: 60
Content-Length: 0
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errormessageId:
x-att-errortext:
x-att-errorvariables:
x-att-errorType:
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=http503

HTTP 503 - without retry:

HTTP/1.0 503 Service Unavailable
Content-Length: 0
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errormessageId:
x-att-errortext:
x-att-errorvariables:
x-att-errorType:
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=http503

Access Token Value Missing or Invalid
This can be due to 2 different scenarios, either the value is completely missing (including the keyword Bearer), or only the token value is missing:

PUT /myservice/v1/items/myitem HTTP/1.1
Host: api.att.com
authorization: 
{message body}
PUT /myservice/v1/items/myitem HTTP/1.1
Host: api.att.com
authorization: Bearer 
{message body}
Error Message due to the above 2 scenarios:
HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: 201
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errorMessageId: POL0001
x-att-errorText: A policy error occurred. Error code is %1
x-att-errorVariables: invalid accesstoken
x-att-errorType: policy
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=POL0001
{
    "requestError": {
        "policyException": {
            "messageId": "POL0001",
            "text": "A policy error occurred. Error code is %1",
            "variables": ["invalid accesstoken"]
        }
    }
}

Missing Authorization Parameter in Header

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: 194
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errorMessageId: SVC1002
x-att-errorText: Missing mandatory parameter %1
x-att-errorVariables: authorization
x-att-errorType: service
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=SVC1002
{
    "requestError": {
        "serviceException": {
            "messageId": "SVC1002",
            "text": "Missing mandatory parameter %1",
            "variables": ["authorization"]
        }
    }
}

Access Token Expired
Access tokens have an expiry time, they can only be used within a certain time duration. If a token is used in a request after the expiry time of the access token, then this error shall be thrown.

HTTP/1.1 419 Authentication Timeout
Content-Type: application/json
Content-Length: 195
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errorMessageId: POL0001
x-att-errorText: A policy error occurred. Error code is %1
x-att-errorVariables: invalid accesstoken
x-att-errorType: policy
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=POL0001
{
    "requestError": {
        "policyException": {
            "messageId": "POL0001",
            "text": "A policy error occurred. Error code is %1",
            "variables": ["invalid accesstoken"]
        }
    }
}

Invalid Scope
If a scope value that is associated with an access token is not the correct scope, then this error shall be thrown.

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: 189
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errorMessageId: POL0001
x-att-errorText: A policy error occurred. Error code is %1
x-att-errorVariables: invalid scope
x-att-errorType: policy
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=POL0001
{
    "requestError": {
        "policyException": {
            "messageId": "POL0001",
            "text": "A policy error occurred. Error code is %1",
            "variables": ["invalid scope"]
        }
    }
}

Exceeded Rate Limit
Each client is designated with a certain rate limit. If the number of requests exceed the maximum allowed within a time period (i.e. seconds, hours, etc), then this error shall be thrown.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Content-Length: 189
Date: Thu, 04 Jun 2014 02:51:59 GMT
x-att-errorMessageId: POL0001
x-att-errorText: A policy error occurred. Error code is %1
x-att-errorVariables: TPS Limit Exceeded
x-att-errorType: policy
x-att-errorInfo: http://developer.att.com/apis/error-detail?error_code=POL0001
{
    "requestError": {
        "policyException": {
            "messageId": "POL0001",
            "text": "A policy error occurred. Error code is %1",
            "variables": ["TPS Limit Exceeded"]
        }
    }
}