Learn how to create JSON Web Tokens to use with MapKit JS.
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
Originheader passed by a browser.
When decoded, a token intended for use with MapKit JS has the following format:
Providing Tokens to MapKit JS
To begin using tokens with MapKit JS, first link to
mapkit in your web page:
MapKit JS calls the
authorization 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
You can set
authorization to a function that returns a new token, or to a function that returns a token as a string. Set
authorization 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
authorization function, and call the
done() function with the result.
authorization 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.
Detecting Token Errors
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.