Article

Creating a Maps Identifier and a Private Key

Create a Maps Identifer and a private key before generating tokens for MapKit JS.

Overview

MapKit JS uses JSON Web Tokens (JWTs) to authenticate map initializations and other API requests. Before you can create a token, you need a Maps Identifer (i.e., Maps ID) and private key that is associated to a Maps ID.

Maps IDs and private keys can be created and associated through your Apple Developer Account. Once you have completed the steps to obtain these items you can construct a JSON Web Token and sign it with your private key, as described in Creating and Using Tokens with MapKit JS.

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, your string might look something like 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 a MapKit JS Private Key

Once you have created a Maps ID, the next steps are to create a private key, add the MapKit JS service to this key, and associate it with 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, and you can begin Creating and Using Tokens with MapKit JS.

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

Creating and Using Tokens with MapKit JS

Learn how to create JSON Web Tokens to use with MapKit JS.

MapKit JS Release Notes

Learn about updates, bug fixes, and API changes for MapKit JS.

Loading the Latest or a Specific Version of MapKit JS

Link to the most recent version of MapKit JS or a version of your choice.

mapkit

The JavaScript API for embedding Apple maps on your website.