Apple Maps — how to connect

The plugin ships one node type, AppleMaps/Maps: a page that is a place search plus a route planner over the Apple Maps Server API. The key is the INSTANCE's — map keys are instance configuration, set once by an administrator in Administration ▸ Maps; people do not enter a key of their own. (A key already stored on an older personal My Maps node keeps working until the migration offers it to the administrator.)

1. Create a MapKit key (Apple Developer Program required)

In developer.apple.com/account:

Certificates, Identifiers & Profiles ▸ Keys ▸ + — name the key and enable MapKit JS. A key made for push notifications or Sign in with Apple signs happily and is refused by the Maps API — the checkbox is the part that matters.
Download the .p8 — Apple offers this exactly once. Note the 10-character Key ID shown beside it.
Your 10-character Team ID is under Membership details.

2. Hand the key to the instance (administrator)

In Administration ▸ Maps, paste the three values; each goes to the instance's Key Vault, is shown only as a mask afterwards, and reaches the portal as configuration:

Setting	Configuration key	Value
Team ID	`AppleMaps:TeamId`	the 10-character Team ID
Key ID	`AppleMaps:KeyId`	the 10-character Key ID
Private key	`AppleMaps:PrivateKey`	the full text of the `.p8` file — BEGIN and END lines included, line breaks intact

The map RENDERER (MapKit JS) reads its own token, AppleMaps:Token, set on the same page.

3. Search and route

Type a place — a name, a POI, an address — and press Search: the hits render with their formatted address, coordinates to five decimals, and Apple's POI category. Set From and To (free text or lat,lon) and the first route renders with its distance and duration.

How the auth works

Apple's Maps API is two-stage: the mesh signs a short-lived (20-minute) ES256 auth token from your .p8, trades it at /v1/token for a ~30-minute access token, and the data calls carry that. Both steps happen server-side inside one fetch — the key never travels, and nothing long-lived is cached. If a data call is refused after a good exchange, the access token expired mid-fetch; Search simply mints a fresh pair.

Security, by design

The .p8 key never leaves the mesh. Only short-lived tokens are derived from it — the 20-minute auth token travels solely to Apple's /v1/token exchange, and the ~30-minute access token solely to Apple's data endpoints, both over HTTPS. Losing either costs minutes of Maps access, nothing more; the key itself is never transmitted anywhere.
Secrets render only as masks. No page shows the values: they are pasted once in Administration ▸ Maps, encrypted on the way, written to Key Vault by the control plane, and read by the portal as configuration.
Revocation is instant: delete the key in the developer portal and every future exchange fails with the named 401 diagnosis.

What the mesh calls

maps-api.apple.com — /v1/token, /v1/search, /v1/directions (and the model also speaks /v1/geocode + /v1/reverseGeocode for other plugins to reuse). All GETs, all through the mesh's bounded HTTP pool; a stalled call degrades to a diagnosis on the page, never a hang.