Article

Getting Keys and Creating Tokens

Obtain developer tokens and keys needed to make requests to the Apple Music API.

Overview

To make requests to the Apple Music API, Create a MusicKit identifier and private key using a developer token to authenticate yourself as a trusted developer and member of the Apple Developer Program. A signed developer token is required in the header of every Apple Music API request.

Create a Developer Token

The Apple Music API supports the JSON Web Token (JWT) specification, so you can pass statements and metadata called claims. For more information, see the JWT specification and the available libraries for generating signed JWTs.

Construct a developer token as a JSON object whose header contains:

  • The encryption algorithm (alg) you use to encrypt the token

  • A 10-character key identifier (kid) key, obtained from your developer account

In the claims payload of the token, include:

  • The issuer (iss) registered claim key, whose value is your 10-character Team ID, obtained from your developer account

  • The issued at (iat) registered claim key, whose value indicates the time at which the token was generated, in terms of the number of seconds since Epoch, in UTC

  • The expiration time (exp) registered claim key, whose value must not be greater than 15777000 (6 months in seconds) from the Current Unix Time on the server.

After you create the token, sign it with your MusicKit private key. Then encrypt the token using the Elliptic Curve Digital Signature Algorithm (ECDSA) with the P-256 curve and the SHA-256 hash algorithm. Specify the value ES256 in the algorithm header key (alg).

A decoded JWT developer token has the following format:

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

Create a Music User Token

For personalized requests, pass a music user token in the header that you obtain using the requestUserToken(forDeveloperToken:completionHandler:) method in the StoreKit framework.

Authenticate Requests

A developer token is a signed and encrypted JWT token used to authenticate a developer in Apple Music requests. For personalized requests, also include a music user token.

In all requests, pass the Authorization: Bearer key set to the developer token:

curl -v -H 'Authorization: Bearer [developer token]' "https://api.music.apple.com/v1/catalog/us/songs/203709340"

For personalized requests, add the Music-User-Token key set to the music user token:

curl -v -H 'Music-User-Token: [music user token]' -H 'Authorization: Bearer [developer token]' "https://api.music.apple.com/v1/catalog/us/songs/203709340"

Simulate the Too Many Requests Error

If you are requesting anything from the Apple Music Catalog, the request will hit our cache first, which doesn't check your rate limit. If you are requesting anything from a personalized endpoint, calling it will always check the rate limit.

You receive the Too Many Requests (429) error when you exceed your request capacity as determined by the server. To simulate this error, make a request to this endpoint: https://api.music.apple.com/v1/test and this MusicKit private key:

-----BEGIN PRIVATE KEY-----
MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgU208KCg/doqiSzsVF5sknVtYSgt8/3oiYGbvryIRrzSgCgYIKoZIzj0DAQehRANCAAQfrvDWizEnWAzB2Hx2r/NyvIBO6KGBDL7wkZoKnz4Sm4+1P1dhD9fVEhbsdoq9RKEf8dvzTOZMaC/iLqZFKSN6
-----END PRIVATE KEY-----

Save this key as a text file with a .p8 file extension, and be sure to keep the key string on one line. In the JWT, set the algorithm (alg) key to ES256, the key identifier (kid) key to CapExedKid, and the issuer (iss) to CapExdTeam.

See Also

First Steps

About the Apple Music API

Learn how Apple Music data is handled using this API.

Handling Requests and Responses

Write a request and handle a response from the Apple Music API.

Using Storefronts and Localizations

Get storefront and localization information for the Apple Music catalog.

Handling Relationships and Pagination

Fetch relationships and paginate response results from the Apple Music API.