Overview
The custom API uses the OAuth 2.0 client-credentials flow. Your integration exchanges its API key and one-time API secret for an opaque Bearer token, then sends that token to the map API.
Use a trusted server
Never put the API secret or token exchange in browser JavaScript, a mobile application bundle, a public repository, a URL, or client-visible map data. A backend, serverless function, or other confidential server process should own the credentials.
- Create a credential in Settings → API integrations.
- Store the API key and secret in your server’s secret store.
- Exchange them for a one-hour Bearer token.
- Call map endpoints with both the Bearer token and exact configured
Origin. - Request a new token when the current token expires. There is no refresh token.
Create a credential
Open Settings → API integrations and select Create new API credential. Your current password confirms this security-sensitive action.
| Field | Meaning |
|---|---|
| Name | A recognizable label for the integration. It is not sent with API requests. |
| Website URL | The exact HTTPS origin that every token and protected API request must carry, for example https://integration.example. Paths and credentials are removed; local development may use HTTP only for localhost or loopback addresses. |
| Permissions | The maximum scopes any token created from this credential may receive. |
| Allow admin rights | Allows the connection to change enabled map modules and connected-website settings. It does not make the account user a MapAPlace administrator. |
The API secret is displayed once. Copy it immediately. MapAPlace stores only a cryptographic digest and cannot show the original secret later. If it is lost or exposed, delete the integration and create a new credential.
Deleting a credential immediately revokes its active tokens. Use a separate credential for every external system so one integration can be revoked without interrupting another.
Get an access token
Send HTTP Basic credentials to POST /api/v1/oauth/token. The username is the API key and the password is the API secret. The body must use application/x-www-form-urlencoded with grant_type=client_credentials.
export MAPAPLACE_URL="https://mapaplace.com"
export MAPAPLACE_ORIGIN="https://your-integration.example"
export MAPAPLACE_API_KEY="api-key_..."
export MAPAPLACE_API_SECRET="your-one-time-secret"
curl --request POST "$MAPAPLACE_URL/api/v1/oauth/token" \
--user "$MAPAPLACE_API_KEY:$MAPAPLACE_API_SECRET" \
--header "Origin: $MAPAPLACE_ORIGIN" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "scope=maps:read maps:write"
Omit scope to receive every scope assigned to the credential, or supply a space-separated subset. Asking for an unassigned scope fails without revealing credential details.
{
"access_token": "opaque-256-bit-token",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "maps:read maps:write"
}
const mapAPlaceUrl = "https://mapaplace.com";
const integrationOrigin = "https://your-integration.example";
const apiKey = process.env.MAPAPLACE_API_KEY;
const apiSecret = process.env.MAPAPLACE_API_SECRET;
const basic = Buffer.from(apiKey + ":" + apiSecret, "utf8").toString("base64");
const body = new URLSearchParams({
grant_type: "client_credentials",
scope: "maps:read maps:write",
});
const response = await fetch(mapAPlaceUrl + "/api/v1/oauth/token", {
method: "POST",
headers: {
Authorization: "Basic " + basic,
"Content-Type": "application/x-www-form-urlencoded",
Origin: integrationOrigin,
},
body,
});
if (!response.ok) throw new Error("Token request failed: " + response.status);
const token = await response.json();
Tokens expire after 3,600 seconds. Cache a token server-side until shortly before expiry, then perform another client-credentials exchange.
Make authenticated requests
Every protected request needs both headers below. The Origin must exactly equal the credential’s Website URL origin, including scheme and any non-default port.
Authorization: Bearer <access-token>Origin: https://your-integration.example
curl "$MAPAPLACE_URL/api/v1/maps?page=1" \
--header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
--header "Origin: $MAPAPLACE_ORIGIN"
{
"maps": [
{
"id": "map_time_entropy",
"slug": "map_time_entropy",
"title": "Visitor map",
"status": "published",
"hasSavedRevision": true,
"hasUnpublishedChanges": false,
"embedAllowedOrigin": "https://www.example.com",
"embedAllowedOriginReadOnly": false,
"accessLevel": "owner",
"createdAt": "2026-07-21T12:00:00.000Z",
"updatedAt": "2026-07-21T12:30:00.000Z"
}
],
"pagination": {
"page": 1,
"pageSize": 10,
"total": 1,
"totalPages": 1
}
}
Map resources are always restricted to the account user who owns the credential. Knowing another map ID does not grant access.
Scopes and admin rights
maps:read
List maps and read map metadata, drafts, published artifacts, and specific revisions.
maps:write
Create map records, save immutable revisions, and upload image assets.
maps:publish
Publish, unpublish, and change the map’s allowed embed origin.
maps:delete
Soft-delete maps owned by the connected account user.
Admin rights are separate from scopes. Without admin rights, a saved revision can change normal map content but MapAPlace preserves the current enabled/disabled module state and other connection-restricted settings. Enable admin rights only for a trusted integration that must manage those settings.
Map endpoints
Use the MapAPlace origin shown beside the generated credential as the base URL. Protected management responses use Cache-Control: no-store.
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/maps?page={page} |
maps:read |
List accessible maps in pages of 10. |
| POST | /api/v1/maps |
maps:write |
Create an empty owned map with a title. |
| GET | /api/v1/maps/{mapId} |
maps:read |
Read safe map metadata. |
| DELETE | /api/v1/maps/{mapId} |
maps:delete |
Soft-delete a map. Only an owner can delete it. |
| PUT | /api/v1/maps/{mapId}/embed-policy |
maps:publish |
Allow one exact HTTPS origin to embed the published viewer. |
| PUT | /api/v1/maps/{mapId}/public-access |
maps:publish |
Enable, change, or remove password protection for public delivery. |
| POST | /api/v1/maps/{mapId}/revisions |
maps:write |
Validate and store a complete immutable map artifact. |
| GET | /api/v1/maps/{mapId}/draft/map.json |
maps:read |
Read the current draft artifact. |
| GET | /api/v1/maps/{mapId}/published/map.json |
maps:read |
Read the current published artifact for the account. |
| GET | /api/v1/maps/{mapId}/revisions/{revisionId}/map.json |
maps:read |
Read a specific accessible revision artifact. |
| POST | /api/v1/maps/{mapId}/publish |
maps:publish |
Publish the current draft revision. |
| POST | /api/v1/maps/{mapId}/unpublish |
maps:publish |
Remove the map from public delivery without deleting its draft. |
Create a map
curl --request POST "$MAPAPLACE_URL/api/v1/maps" \
--header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
--header "Origin: $MAPAPLACE_ORIGIN" \
--header "Content-Type: application/json" \
--data '{"title":"Visitor map"}'
The response is 201 Created with { "map": { ... } }. The returned map.id is used in later requests. A newly created map has no saved revision until you upload an artifact.
Save a revision
curl --request POST \
"$MAPAPLACE_URL/api/v1/maps/map_time_entropy/revisions" \
--header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
--header "Origin: $MAPAPLACE_ORIGIN" \
--header "Content-Type: application/json" \
--data @revision-request.json
{
"title": "Visitor map",
"artifact": {
"format": "mapaplace-map",
"formatVersion": 1,
"revisionId": "revision_time_entropy",
"encoding": "gzip+base64url",
"compressedBytes": 312,
"uncompressedBytes": 540,
"checksum": "sha256:64-lowercase-hex-characters",
"payload": "base64url-encoded-gzip-data"
}
}
Revisions are immutable. Every save needs a new valid revisionId. Reusing a revision ID returns 409 Revision already exists. The route validates the artifact, checksum, map identity, schema, canonical JSON, compressed sizes, and extension limits before storage.
Map artifact contract
Draft, published, and historical map.json endpoints return an encoded artifact. The payload is URL-safe base64 without padding containing a gzip-compressed, canonical UTF-8 JSON document. checksum is the SHA-256 digest of the uncompressed document bytes.
To update an existing map, fetch its draft artifact, decode and decompress the payload, update the document through a compatible MapAPlace client, then create a new canonical artifact and revision ID. Do not edit only the outer metadata or reuse a checksum.
{
"baseMap": {
"providerId": "openfreemap-liberty",
"showBuildings": true,
"show3dBuildings": false,
"showPois": true
},
"camera": {
"longitude": -0.1276,
"latitude": 51.5072,
"zoom": 11,
"pitch": 0,
"bearing": 0
},
"controls": {
"zoom": true,
"fullscreen": true,
"distanceScale": true
}
}
import { createHash, randomUUID } from "node:crypto";
import { gzipSync } from "node:zlib";
function createMapAPlaceId(prefix) {
const timestamp = Date.now().toString(36).padStart(9, "0");
const entropy = randomUUID().replaceAll("-", "").toLowerCase();
return prefix + "_" + timestamp + "_" + entropy;
}
function canonicalize(value) {
if (Array.isArray(value)) return value.map(canonicalize);
if (value && typeof value === "object") {
return Object.fromEntries(
Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
);
}
return value;
}
function createMapArtifact(mapId, coreDocument, extensions = {}) {
const document = canonicalize({
...coreDocument,
extensions,
mapId,
schemaVersion: 1,
});
const uncompressed = Buffer.from(JSON.stringify(document), "utf8");
const compressed = gzipSync(uncompressed);
return {
format: "mapaplace-map",
formatVersion: 1,
revisionId: createMapAPlaceId("revision"),
encoding: "gzip+base64url",
compressedBytes: compressed.byteLength,
uncompressedBytes: uncompressed.byteLength,
checksum: "sha256:" + createHash("sha256").update(uncompressed).digest("hex"),
payload: compressed.toString("base64url"),
};
}
The helper shows the version 1 envelope and identifier algorithm. Validate application input before passing it to the helper; the MapAPlace server remains authoritative and rejects documents outside the contract.
Core document rules
schemaVersionis currently1and is added during artifact creation.- Longitude is −180 to 180, latitude is −90 to 90, zoom is 0 to 24, pitch is 0 to 85, and bearing is −180 to 180.
- Optional camera bounds require explicit
boundsEnabledand southwest/northeast values. - All control and base-map feature switches are explicit booleans.
extensionsis an object keyed by installed module ID. Extension schemas and required premium access remain module-specific.- The uncompressed document limit is 512 KiB. Unknown fields, unsafe keys, invalid numbers, and non-canonical key ordering are rejected.
Routing provider credentials are never accepted inside a map artifact; use the map editor’s protected credential controls for those secrets.
Publish and embed
curl --request POST \
"$MAPAPLACE_URL/api/v1/maps/map_time_entropy/publish" \
--header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
--header "Origin: $MAPAPLACE_ORIGIN"
curl --request PUT \
"$MAPAPLACE_URL/api/v1/maps/map_time_entropy/embed-policy" \
--header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
--header "Origin: $MAPAPLACE_ORIGIN" \
--header "Content-Type: application/json" \
--data '{"allowedOrigin":"https://www.example.com"}'
| Public URL | Purpose |
|---|---|
GET /api/v1/public/maps/{slug} | Public title and status metadata for a published map. |
GET /api/v1/public/maps/{slug}/map.json | The current published artifact. Supports ETag and If-None-Match. |
POST /api/v1/public/maps/{slug}/access | Exchange the map password for a short-lived map access token. |
GET /maps/{slug} | Standalone public map viewer. |
GET /embed/maps/{slug} | Embeddable viewer, restricted to the configured embed-policy origin. |
Unprotected public artifact responses may be cached for 15 minutes and can use stale content during a temporary error. Password-protected responses are private and are not cached. Drafts, revision history, and account metadata are never exposed by public routes. Unpublishing immediately removes the public map routes and viewer.
Image assets
Upload raw JPEG, PNG, SVG, or WebP bytes with maps:write. Files must be no larger than 5 MiB and no wider or taller than 4,096 pixels. MapAPlace validates and normalizes the image to managed WebP.
curl --request POST "$MAPAPLACE_URL/api/v1/assets/images" \
--header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
--header "Origin: $MAPAPLACE_ORIGIN" \
--header "Content-Type: image/png" \
--data-binary @marker.png
A successful 201 response contains the asset ID, final MIME type, dimensions, checksum, creation time, and previewUrl. Metadata is available from GET /api/v1/assets/{assetId}; normalized bytes are available from GET /api/v1/assets/{assetId}/preview.
Errors, status codes, and limits
Most failures return JSON with one safe error message:
{
"error": "Insufficient scope"
}
| Status | Meaning |
|---|---|
400 | Invalid body, pagination, origin, map artifact, or field value. |
401 | Missing, invalid, expired, revoked, or wrong-origin credentials/token. |
403 | The token lacks the required scope. |
404 | The resource is missing or is not accessible to this credential’s user. |
409 | The revision ID already exists. |
429 | Rate limit exceeded. Respect Retry-After and retry with backoff. |
500 | An internal storage or processing operation failed. |
Current rate limits
- Token exchange: 20 requests per minute.
- Map reads and listings: 300 requests per minute.
- Map creation and revision writes: 60 requests per minute.
- Publish, unpublish, embed-policy, public-access, and delete operations: 20 to 30 requests per minute.
- Map password attempts: 10 requests per minute.
- Public map delivery: 600 requests per minute.
Security checklist
- Use HTTPS in production and verify TLS certificates.
- Keep the API secret and access tokens in a server-side secret store.
- Create one credential per integration and grant only required scopes.
- Leave admin rights disabled unless module and connected-site settings must be changed.
- Send the exact configured
Originon token and Bearer requests. - Do not log Authorization headers, API secrets, Bearer tokens, or complete credential responses.
- Delete a credential immediately if it is exposed or no longer used.
- Treat all IDs as opaque strings and all API responses as untrusted input requiring normal error handling.