Web Service Endpoint

Sending an Authentication Message

Pass authentication data between the business or Customer Service Platform and the customer's device using OAuth.


POST https://mspgw.push.apple.com/v1/authenticate

HTTP Headers


A Boolean that determines whether the reply is sent by a person or an automated bot.


A list of string that identities Business Chat features that the customer device supports.


A string that identifies the message recipient.


A string that identifies the operating system type of the customer’s device.


A UUID string that identifies the message.


A string that identifies the agent or system sending the request.


A string that identifies the message sender.


A numerical version number of the message extension schema; the version should be 1.0.


Response Codes


The request was successful.

400 Bad Request
Bad Request

The request lacks required field or was malformed.

401 Unauthorized

The request lacks Authorization header.

403 Forbidden

The request failed to validate the Authorization header field.

404 Not Found
Not Found

The request failed to recognize the destination-id value.

500 Internal Server Error
Internal Server Error

A server error occurred.


Businesses must supply authentication details about the OAuth provider, including authentication endpoint URLs, client identifier, and business information verified by Apple Business Register. Changing any of these authentication parameters requires additional verification and approval from multiple customers that own or administer the business.

Pass Authenticate Data

Passing authenticate data requires sending a POST request to the /v1/authenticate endpoint hosted by Business Chat with the authenticate message in the request body. You must secure the authenticate endpoint before sending a request from a business to the customer. When the OAuth request is sent to the provider, the endpoints must present a valid Extended Validation (EV) certificate for a successful authorization.

You use the AuthenticateRequestBody.Authenticate dictionary key and the responseEncryptionKey to authenticate with the OAuth provider endpoints. This workflow enables the OAuth provider to audit the public key used to encrypt the authentication token. Use the requestIdentifier in the data dictionary to identify the authentication request and map the OAuth token in the response to the request originator. Either the business or the CSP generates the requestIdentifier and responseEncryptionKey.

Business Chat returns a JSON dictionary containing the encrypted token field. The business or CSP can decrypt the access token and verify the user's access. If the business is responsible for decrypting the access token, the business and CSP must implement the delegation of key generation and token verification. The tall, rectangular boxes on the vertical lines in Figure 1 denote key generation and access token verification.

Figure 1

Authentication flow between a CSP and a user's device

A diagram showing the authentication flow and data as it is passed between a business/CSP and a user's device.

Validate the Public Key

Business Chat authentication uses OAuth to provide a way for the authentication provider and the business to audit the public key sent in a user's authentication request. The audit detects when a public key has been tampered with or replaced, which could result in the customer's authentication token leaking to an unintended party.

When a user's device makes the HTTPS call to the authorization endpoint, it includes two additional request parameters in addition to the standard authentication request: responseEncryptionKey and userHandle. The authentication provider can make an API call to the business with the responseEncryptionKey and the user's opaque ID.

If the business is acting as its own authentication provider, it checks these values against its internal database. If the business made a request with that customer's key, the authentication provider proceeds by sending back the code or access token. If the customer's key does not match the parameter values in its pending requests, the customer's key may have been tampered with and the authentication provider must immediately fail the request from the device.

Compose an Authentication Request

The authenticate request is an interactive message. When composing an authenticate request, include the AuthenticateRequestBody.Authenticate dictionary key in the BaseInteractiveMessage dictionary to describe the behavior and content of the authentication request.

You can send authentication data to a customer’s device with the auth capability announced, which is included in the capabilities header of the message request. Devices that support authenticate messages have iOS 12 or later and macOS 10.14.0 or later. For more information about the Authorization header field, see Authorize a Message.

Successful Authentication

Example of an authentication request. Note that the clientSecret key is forwarded to the authentication provider as client_secret.

{ "type": "interactive", “interactiveData”: { "bid": "com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.icloud.apps.messages.business.extension",    "data": {        “version": "1.0",        "requestIdentifier": "3EF748B5-<truncated>",        "authenticate" : {            "oauth2": {                "responseType" : "code",                "scope" : ["email", "profile"],                "state" : "security_token",                "responseEncryptionKey" : “BFz948MTG3OQ0Q69 <truncated>“,                "clientSecret" : "client_secret"            }        },        "images": [            {               "data": “iVBORw0KGgoAAAANSUhEUgAA <truncated>",               "identifier": "1"            }        ]    },    "receivedMessage": {        "title": "Sign In to Business Chat Sandbox",        "imageIdentifier": "1"    },    "replyMessage": {        "title": "You Signed In",        "imageIdentifier": "1"    }}
{    "data": {        "version": "1.0",        "requestIdentifier": "8EF748B5-<truncated>",        "authenticate": {            "status":"authenticated",            "token": "<An encrypted Base64-encoded token.>"        },        "images": [{                   "data": "iVBORw0KGgoAAAANSUhEUgAAADIA <truncated>",                   "identifier": "1"                   }]    },    "bid": "com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.icloud.apps.messages.business.extension",    "receivedMessage": {        "title": "Sign In to Business Chat Sandbox",        "subtitle": "Authentication required to access your customer data",        "style": "icon",        "imageIdentifier": "1"    },    "replyMessage": {        "title": "You Signed In",        "subtitle": "",        "style": "icon",        "imageIdentifier": "1"    }}

Failed Authentication

{ "type": "interactive", “interactiveData”: { "bid": "com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.icloud.apps.messages.business.extension",    "data": {        “version": "1.0",        "requestIdentifier": "3EF748B5-<truncated>",        "authenticate" : {            "oauth2": {                "responseType" : "code",                "scope" : ["email", "profile"],                "state" : "security_token",                "responseEncryptionKey" : “BFz948MTG3OQ0Q69JHUiBG7 <truncated>“,                "clientSecret" : "client_secret"            }        },        "images": [            {               "data": “iVBORw0KGgoAAAANSUhEUgA <truncated>",               "identifier": "1"            }        ]    },    "receivedMessage": {        "title": "Sign In to Business Chat Sandbox",        "imageIdentifier": "1"}
{    "data": {        "version": "1.0",        "requestIdentifier": "8EF748B5-<truncated>",        "authenticate": {            "status":"failed",            "errors": [{                "code": 2,                "domain": "com.apple.icloud.messages.business.cryptor",                "message": "Key is not UTF8"              }]        },        "images": [{                   "data": "iVBORw0KGgoAAAANSUhEUgAA <truncated>",                   "identifier": "1"                   }]    },    "bid": "com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.icloud.apps.messages.business.extension",    "receivedMessage": {        "title": "Sign In to Business Chat Sandbox",        "subtitle": "Authentication required to access your customer data",        "style": "icon",        "imageIdentifier": "1"    },    "replyMessage": {        "title": "Authentication Failed",        "subtitle": "",        "style": "icon",        "imageIdentifier": "1"    }