Article

Creating and Using Tokens with MapKit JS

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

Overview

MapKit JS uses JSON Web Tokens (JWTs) to authenticate map initializations and other API requests, such as requests to retrieve directions or execute a search. You must have a signed developer token in order to initialize MapKit JS.

To begin using JWTs with MapKit JS, first obtain a Maps ID and a private key as described in Creating a Maps Identifier and a Private Key. Then construct a token as a JSON object with the required fields in the header and payload, use your private key to sign the token, and provide that token to MapKit JS. Make sure to confirm the success of the token authorization.

Create a MapKit JS Token

A JSON Web Token (JWT) is required to initialize the mapkit object. JWTs include a header and a payload. The payload lets you pass metadata called claims, and the header describes the cryptographic operations applied to the JWT claims set.

Construct a developer token as a JSON object whose header contains these required fields:

  • The encryption algorithm (alg) used to encrypt the token. ES256 should be used to encrypt your token, and the value for this field should be "ES256".

  • A 10-character key identifier (kid) key, obtained from your Apple Developer account.

  • A type parameter (typ), with the value "JWT".

In the claims payload of the token, include the following required keys:

  • The Issuer (iss) registered claim key. This key's value is your 10-character Team ID, obtained from your developer account.

  • The Issued At (iat) registered claim key. The value of this key indicates the time at which the token was generated, in terms of the number of seconds since UNIX Epoch, in UTC.

  • The Expiration Time (exp) registered claim key, in terms of the number of seconds since UNIX Epoch, in UTC.

To specify that this token should only used by a specific website, include the optional origin key in the claims payload:

  • The Origin (origin) key. This key's value is a fully qualified domain that should match the Origin header passed by a browser.

When decoded, a token intended for use with MapKit JS has the following format:

{
    "alg": "ES256",
    "kid": "ABC123DEFG",
    "typ": "JWT"
}
{
    "iss": "DEF123GHIJ",
    "iat": 1437179036,
    "exp": 1493298100,
    "origin": "https://mywebsite.org"
}

To learn more about all aspects of JWTs, see the JSON Web Token (JWT) specification. You can find a collection of libraries available for generating signed JWTs at https://jwt.io.

Providing Tokens to MapKit JS

To begin using tokens with MapKit JS, first link to mapkit.js in your web page:

<script src="https://cdn.apple-mapkit.com/mk/5.x.x/mapkit.js"></script>

Next initialize the mapkit object with the init function. Pass an object to the init function that includes a required authorizationCallback function, and an optional language property.

MapKit JS calls the authorizationCallback function whenever it detects that a new token is needed. For example, if MapKit JS detects that a token has expired, it will attempt to asynchronously retrieve a new one by calling your authorizationCallback function.

You can set authorizationCallback to a function that returns a new token, or to a function that returns a token as a string. Set authorizationCallback to a function that returns a new token if you want to use short-lived tokens provided from your server. Sign tokens on your server using the libraries available at https://jwt.io, then expose a service that returns a new signed token whenever the service endpoint is called. Call the service endpoint in your authorizationCallback function, and call the done() function with the result.

mapkit.init({
    authorizationCallback: function(done) {
        fetch("/gettoken")
            .then(res => res.text())
            .then(done);
    },
    language: "es"
});

Setting authorizationCallback to a function that returns a token as a string is useful for local development, or if you want to use a long-lived token with MapKit JS. Sign a token locally on your development machine with an expiration, then use the token directly in your code. Whether you are using a short-lived or long-lived token, setting the origin claim is always recommended.

mapkit.init({
    authorizationCallback: function(done) {
        done("your-token-string-here");
    },
    language: "es"
});

Detecting Token Errors

To understand when token authorization fails, listen for the error event on the mapkit object, as described in Handling Initialization Events.

The mapkit object emits an event when it is successfully initialized, and when initialization fails. Listening for the error event on the mapkit object and inspecting the status codes returned in this event can help you understand whether a token is invalid, or whether too many requests have already been made for the Team ID associated with the token. If your token is invalid, verify that your JWT includes all of the required fields and that all fields are correct — for example, you may have the origin claim set to the URL of your public website, but you are using the token for development on another domain. If you have exceeded the number of requests allowed for your Team ID, you can request more at https://developer.apple.com/mapkitjs.

See Also

MapKit JS

Creating a Maps Identifier and a Private Key

Create a Maps Identifer and a private key before generating tokens for 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.