Establishing a token-based connection to APNs

Overview

Token-based authentication offers a stateless way to communicate with APNs. Stateless communication is faster than certificate-based communication because it doesn’t 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 or a subset 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. To learn more about key creation, see Create a private key to access a service.

Team-scoped keys

Use team-scoped keys to generate authentication tokens for sending notifications to any topic in a team. These keys restrict usage to either Sandbox or Production, enhancing security. They apply to all existing and new topics in the team. Each environment can have a maximum of two keys.

Topic-specific keys

Use topic-specific keys to generate authentication tokens for sending notifications to specific team topics within a single environment. These keys provide granular control and simplify management. You can create a maximum of 200 keys for Sandbox and 200 for Production, with up to 400 topics per topic-based key.

A topic-specific key can have at most one related key in the same environment. When you connect to the APNs server, you can use authentication tokens from both the topic-based key and its related key (if available) for push notification requests.

Obtain an encryption key and key ID from Apple

You need an APNs authentication token signing key to generate the tokens that your server uses. You request this key from your developer account on developer.apple.com, as shown in the following image:

[Image]

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. You can find instructions to get this ID in Get a key identifier.

• An authentication token signing key, specified as a text file (with a .p8 file extension).

Secure both pieces of information carefully. You 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 use an authentication token, see the authorization header field in Sending notification requests to APNs.

Create and encrypt your JSON token

The token that you include with your notification requests uses the JSON Web Token (JWT) specification. The following table describes the four key-value pairs the token itself contains:

The keys divide 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. The code snippet below shows an example of a JSON token for a fictional developer account.

{
   "alg" : "ES256",
   "kid" : "ABC123DEFG"
}
{
   "iss": "DEF123GHIJ",
   "iat": 1437179036
}

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 RFC 7519.

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:

authorization = bearer eyAia2lkIjogIjhZTDNHM1JSWDciIH0.eyAiaXNzIjogIkM4Nk5WOUpYM0QiLCAiaWF0I
		 jogIjE0NTkxNDM1ODA2NTAiIH0.MEYCIQDzqyahmH1rz1s-LFNkylXEa2lZ_aOCX4daxxTZkVEGzwIhALvkClnx5m5eAT6
		 Lxw7LZtEQcH6JENhJTMArwLf3sXwi

For information on 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’s more than one hour old. Similarly, APNs report an error if you use a new token more than once every 20 minutes on the same connection.

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.

Team and bundle ID mapping

You can’t map a connection to APNs to multiple teams. If you manage APNs for multiple developer accounts, open separate connection pools for each of them.

As part of the authentication process, APNs relates a team ID and associated bundle IDs to a connection on the first push. After the authentication process, attempting to associate a different team or sending a push to a newly added bundle ID causes an error. To send remote notifications to a new topic, add the topic to your team in App Store Connect and create new connections to APNs.

For transferred apps, close and recreate any existing connections from your push provider server to APNs. If you don’t, APNs can’t start accepting push requests from the new team.

See Also

Security

• Establishing a certificate-based connection to APNs