Skip to main content
The Apple Maps Server API requires an authorization token — a long-lived JWT (typically valid for one year) that you generate in the Apple Developer portal. The SDK exchanges this token automatically for short-lived access tokens (valid for approximately 30 minutes) and refreshes them as needed, so your application code only ever handles the long-lived JWT.
Creating a Maps Identifier and private key requires a paid Apple Developer Program membership ($99/year).

​
Create an authorization token

1

Sign in to the Apple Developer portal

Go to developer.apple.com and sign in with your Apple ID enrolled in the Apple Developer Program.
2

Create a Maps Identifier

In the portal, navigate to Certificates, Identifiers & Profiles, then Identifiers. Create a new identifier of type Maps IDs. Give it a descriptive name and ID (for example, maps.com.yourcompany.backend).Full instructions: Creating a Maps Identifier and a Private Key
3

Create a private key

In Keys, create a new key and enable the MapKit JS capability. Select the Maps Identifier you created in the previous step. Download the .p8 private key file — Apple only lets you download it once.
4

Generate the JWT

Use Apple’s token maker at maps.developer.apple.com/token-maker to generate your long-lived JWT. You’ll need:
  • Your Team ID (visible in the top-right of the Developer portal)
  • Your Maps Identifier (the maps.com.yourcompany.backend ID from the previous step)
  • Your Key ID (shown on the key detail page)
  • The .p8 private key file you downloaded
The token maker signs the JWT and lets you set an expiry up to one year from today.

​
The origin claim

When you generate a JWT with a specific origin claim (an HTTP Origin URL bound to the token), every request to the Apple Maps Server API must include that value as the Origin header. If your token has an origin claim, set APPLE_MAPS_ORIGIN to the same value — the SDK reads it and sends it automatically. If your token has no origin claim, you can omit APPLE_MAPS_ORIGIN entirely.

​
Initialize the client

Read the token and optional origin from environment variables or JVM system properties, then pass them to AppleMaps: 
String token = System.getenv("APPLE_MAPS_TOKEN");
if (token == null || token.isBlank()) {
    token = System.getProperty("APPLE_MAPS_TOKEN");
}
if (token == null || token.isBlank()) {
    throw new IllegalStateException("Set APPLE_MAPS_TOKEN as an environment variable or JVM system property.");
}

String origin = System.getenv("APPLE_MAPS_ORIGIN");
if (origin == null || origin.isBlank()) {
    origin = System.getProperty("APPLE_MAPS_ORIGIN");
}

AppleMaps api = (origin == null || origin.isBlank())
    ? new AppleMaps(token)
    : new AppleMaps(token, origin);
Once the client is initialized, the SDK handles access token exchange and refresh automatically — you do not need to manage short-lived tokens yourself.
See Environment variables for all the ways to supply APPLE_MAPS_TOKEN and APPLE_MAPS_ORIGIN to your application.