Secure your communications with APNs using stateless authentication tokens.
Token-based authentication offers a stateless way to communicate with APNs. Stateless communication is faster than certificate-based communication because it does not require APNs to look up the certificate, or other information, related to your provider server. There are other advantages to using token-based authentication:
You can use the same token from multiple provider servers.
You can use one token to distribute notifications for all of your company’s apps.
Token-based requests are slightly larger than certificate-based requests because each request contains the token. You must also update and encrypt your tokens at least once an hour using the provider token signing key that Apple provides you.
Obtain an Encryption Key and Key ID from Apple
When you request a key, Apple gives you:
A 10-character string with the Key ID. You must include this string in your JSON tokens.
An authentication token signing key, specified as a text file (with a
Secure both pieces of information carefully. You will use the authentication token signing key to encrypt your JSON tokens, so this key must remain private to prevent anyone else from generating those tokens.
For detailed instructions on how to request an authentication token signing key, see Communicate with APNs using authentication tokens in Xcode Help.
Create and Encrypt Your JSON Token
The token that you include with your notification requests uses the JSON Web Token (JWT) specification. The token itself contains four key-value pairs, which are described in Table 1.
The encryption algorithm you used to encrypt the token. APNs supports only the ES256 algorithm, so set the value of this key to
The 10-character Key ID you obtained from your developer account; see Obtain an Encryption Key and Key ID from Apple.
The issuer key, the value for which is the 10-character Team ID you use for developing your company’s apps. Obtain this value from your developer account.
The “issued at” time, whose value indicates the time at which this JSON token was generated. Specify the value as the number of seconds since Epoch, in UTC. The value must be no more than one hour from the current time.
The keys are divided between the header and claims payload of the JSON Web Token. The header of the token contains the encryption algorithm and Key ID, and the claims payload contains your Team ID and the token generation time. Listing 1 shows an example of a JSON token for a fictional developer account.
Encrypt the resulting JSON data using your authentication token signing key and the specified algorithm. Your provider server must include the resulting encrypted data with all notification requests.
For detailed information about the JWT specification, see https://tools.ietf.org/html/rfc7519. For additional information about JWT, along with a list of available libraries for generating signed JWTs, see https://jwt.io.
Attach Your Token to Notification Requests
When creating the POST request for a notification, include your encrypted token in the
authorization header of your request. The token is in Base64URL-encoded JWT format, and is specified as
bearer <token data>, as shown in the following example:
For information about how to construct your POST requests, see Sending Notification Requests to APNs.
Refresh Your Token Regularly
For security, APNs requires you to refresh your token regularly. Refresh your token no more than once every 20 minutes and no less than once every 60 minutes. APNs rejects any request whose token contains a timestamp that is more than one hour old. Similarly, APNs reports an error if you recreate your tokens more than once every 20 minutes.
On your provider server, set up a recurring task to recreate your token with a current timestamp. Encrypt the token again and attach it to subsequent notification requests.