Generating JSON Web Tokens for API requests

Overview

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a way to securely transmit information. The App Store Server API and External Purchase Server API require a JWT to authorize each request you make to the API. You create the token, signing it with the private key you downloaded from App Store Connect. For more information about creating keys, see Creating API keys to authorize API requests.

To generate a signed JWT:

1. Create the JWT header.

2. Create the JWT payload.

3. Sign the JWT.

Include the signed JWT in the authorization header of each API request. Generate a new signed JWT for each new request.

Create the JWT header

To create a JWT to communicate with the App Store Server API or External Purchase Server API, use the following fields and values in the header:

To get your key ID, copy it from App Store Connect by logging in to App Store Connect, then:

1. Select Users and Access, then select the Keys tab.

2. The key IDs appear in a column under the Active heading. Hover the cursor next to a key ID to display the Copy Key ID link.

3. Click Copy Key ID.

If you have more than one API key, copy the key ID of the private key that you use to sign the JWT.

Here’s an example of a JWT header:

{
  "alg": "ES256",
  "kid": "2X9R4HXF34",
  "typ": "JWT"
}

Create the JWT payload

The JWT payload contains information specific to the App Store Server API and External Purchase Server API, such as issuer ID and expiration time. Use the following fields — also known as JWT claims — to include these values in the JWT payload:

To get your issuer ID, log in to App Store Connect, then:

1. Select Users and Access, then select the Keys tab.

2. The issuer ID appears near the top of the page. To copy the issuer ID, click Copy next to the ID.

Here’s an example of a JWT payload:

{
  "iss": "57246542-96fe-1a63e053-0824d011072a",
  "iat": 1623085200,
  "exp": 1623086400,
  "aud": "appstoreconnect-v1",
  "bid": "com.example.testbundleid"
}

Note that the JWT is valid for up to one hour after the time you indicate in the iat field, or it expires sooner if you set the exp field for an earlier time.

Sign the JWT

Use the private key associated with the key ID you specified in the header to sign the token using ES256 encryption.

There are a variety of open source libraries available online for creating and signing JWT tokens. See JWT.io for more information. For calls to the App Store Server API, consider using the App Store Server Library to create the JWTs instead. For more information, see Simplifying your implementation by using the App Store Server Library.

Include the JWT in the authorization header of the request

After you create and sign the JWT, provide it in the request’s authorization header as a bearer token.

The following example for the App Store Server API shows a curl command using a bearer token. Replace the text [signed token] with the value of the signed JWT itself. Replace {transactionId} with a transaction identifier of your customer.

curl -v -H 'Authorization: Bearer [signed token]' 
"https://api.storekit.apple.com/inApps/v1/subscriptions/{transactionId}"

See Also

Essentials

• Simplifying your implementation by using the App Store Server Library
• Creating API keys to authorize API requests
• Identifying rate limits
• App Store Server API changelog