Get Tile Tokens Batch
const url = 'https://example.com/tiles/tokens/';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"dataset_ids":["2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/tiles/tokens/ \ --header 'Content-Type: application/json' \ --data '{ "dataset_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] }'Generate tile tokens for up to 50 datasets in one request.
The list must hold between 1 and 50 ids, and a request outside that is 422.
One round trip in place of one request per dataset, which is what a map with many layers would otherwise need.
A dataset that cannot be found or cannot be authorized does not fail the
batch: that id maps to {"error": "..."} in the response instead, so
check each entry for an error key before using it. Duplicate ids are
collapsed.
The request as a whole still fails 401 in one case: a request that carried a credential which did not resolve and that no capability authorized answers 401 rather than a body of per-dataset errors. A request carrying no credential is served normally.
X-Embed-Token is accepted as a fallback authorization for the datasets
inside that token’s scope, so an embedded map can build a terrain source
from real bounds and zoom limits.
Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “ Header Parameters ”Request Body required
Section titled “ Request Body required ”Batch request for tile tokens — accepts up to 50 dataset IDs.
object
Dataset IDs to generate tokens for. Must be unique; duplicates deduplicated server-side.
Example generated
{ "dataset_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ]}Responses
Section titled “ Responses ”Successful Response
Batch response mapping dataset_id (string) to token or error.
Each entry is either a VectorTileToken, a RasterTileToken, or a
{"error": "..."} object describing why the token could not be
generated (404 dataset, 403 forbidden, etc.). The batch call itself
succeeds even if individual datasets fail — clients should check each
entry for the error key.
object
object
object
A raster tile template, signed like its vector sibling.
fix(#688): the raster shape used to carry no signature at all, so a client
following the API contract literally received an unauthenticated template
for a private raster. MapLibre issues the tile image requests itself and
attaches no X-Api-Key, so an API-key-only client could not render one —
the workarounds were setTransformRequest (not available to every consumer)
or ?api_key= in the tile URL, which puts a non-expiring unscoped
credential into tile URLs, server logs, and saved client project files.
tile_url now arrives with sig/exp/scope already in its query string,
so the template is self-sufficient and expires. The three are also returned
as fields, mirroring VectorTileToken, for clients that rebuild the URL.
object
object
Example
{ "tokens": { "additionalProperty": { "kind": "vector" } }}Bad request — invalid query parameters or payload
Unauthenticated — a credential was supplied and could not be resolved (expired, revoked, or malformed). Sending no credential at all is not an error on these operations; they answer anonymously with the public subset. Neither is sending an unresolvable credential alongside a capability that authorizes the request on its own — a valid X-Embed-Token or a valid signed tile template (sig, exp, scope). Those are served and the unrelated credential is ignored.
Not found
Validation error
Internal server error
Service unavailable — the database could not serve the request