Article

Setting Up MapKit JS

Complete a one-time setup to create a Maps ID and obtain a private key to use with MapKit JS.

Overview

MapKit JS uses JSON Web Tokens (JWT) to authenticate map initializations and other API requests. To create tokens that validate you as a trusted developer and member of the Apple Developer Program, first create a Maps ID (i.e., Maps identifier) through your Apple Developer Account. Then create a private key, and associate your Maps ID to this key.

When you are ready to create a token, sign it with your key. JWT is an open standard, and JWTs can be generated using one of the many libraries available at jwt.io.

Create a Maps ID

A Maps ID is a string that you provide to identify a domain or environment that calls the MapKit JS API. Maps IDs use reverse-domain-style notation with three or four fields separated by a dot. The first field must be maps; the remainder or this string can be a name that's meaningful to you. For example: maps.com.mywebsite or maps.com.mycompany.mywebsite.

To create a Maps ID, follow these steps:

  1. Go to developer.apple.com/account and login with your Apple Developer credentials.

  2. Under Certificates, Identifiers & Profiles, select Maps IDs under Identifiers in the sidebar.

  3. In the upper-right corner, click the Add button (+), then click Continue.

  4. Enter a string for the description. This could be your app name, team name, project name, or something that conveys context and is meaningful to you.

  5. Enter a reverse-domain-style string for the identifier (for example, maps.com.mycompany.mywebsite), then click Continue.

  6. Review the information, then click Register.

  7. Click Done.

If you have multiple environments, such as a development environment and a production environment, it’s a good practice to create separate Maps IDs and keys for each environment. That way if a key used in production becomes compromised, revoking it will not affect your UAT or test environments.

Obtain MapKit JS Private Key

To use a private key with MapKit JS, first create a key through your Apple Developer Account. Then add the MapKit JS service to this key, and associate a Maps ID:

  1. In Certificates, Identifiers & Profiles, select All under Keys, then click the Add button (+) in the upper-right corner.

  2. Under Key Description, enter a unique name for the key.

  3. Under Key Services, select the checkbox next to MapKit JS, then click Continue. Note that if the MapKit JS checkbox is disabled, you have not created a Maps ID.

  4. Click Configure next to the checkbox. On the next page, choose a Maps ID to associate to this key from the pop-up menu, then click Continue.

  5. Review the key configuration, then click Confirm.

  6. Optionally, click Download to download the key. The private key is available to download a single time. If the Download button is disabled, you previously downloaded the key.

  7. Click Done.

After executing these steps, you will have a private key that can be used to sign JWTs. These tokens authorize your calls to the MapKit JS API.

The private key is a shared secret between you and Apple. To keep your private key secure, do not put your private key in public facing client-side code, and do not share the key.

The private key doesn't expire, but you can revoke it. Revoking a key makes it invalid and affects calls to the MapKit JS API. If you lose a key or if someone else starts using your key, you should revoke it. See Revoke, edit, and download keys for more information.

See Also

MapKit JS

MapKit JS Release Notes

Learn about changes to the MapKit JS API.

mapkit

The JavaScript API for embedding Apple maps on your website.