Pass authentication data between the business or Customer Service Platform and the customer's device using OAuth.
- Business Chat API 1.0+
.push .apple .com /v1 /authenticate
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.
The request was successful.
400 Bad Request
The request lacks required field or was malformed.
The request lacks Authorization header.
The request failed to validate the Authorization header field.
404 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
response 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
request 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
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.
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:
user. The authentication provider can make an API call to the business with the
response 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.