Get Tile Token

GET

/tiles/token/{dataset_id}/

const url = 'https://example.com/tiles/token/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/tiles/token/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/

Generate a tile token for a dataset.

For vector datasets: returns HMAC-signed token (sig, exp, scope, expires_in). For raster datasets: returns tile URL template and metadata.

Both responses include a discriminated kind field.

Public datasets can be accessed without authentication. Private/restricted datasets require authentication and RBAC checks.

Authorizations

Parameters

Path Parameters

dataset_id

required

Dataset Id

string format: uuid

Responses

200

Successful Response

application/json

Any of:

VectorTileToken
RasterTileToken

VectorTileToken

object

kind

required

Kind

string

Allowed value: vector

sig

required

Sig

string

exp

required

Exp

integer

scope

required

Scope

string

expires_in

required

Expires In

integer

RasterTileToken

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

kind

required

Kind

string

Allowed value: raster

tile_url

required

Tile Url

string

sig

required

Sig

string

exp

required

Exp

integer

scope

required

Scope

string

expires_in

required

Expires In

integer

bounds

required

Any of:

Array<number>
null

Array<number>

minzoom

required

Minzoom

integer

maxzoom

required

Maxzoom

integer

tile_size

required

Tile Size

integer

format

required

Format

string

Example

{
  "kind": "vector"
}

400

Bad request — invalid query parameters or payload

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

401

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.

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

404

Not found

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

422

Validation error

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

500

Internal server error

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

503

Service unavailable — the database could not serve the request

application/problem+json

ProblemDetail

object

type

Type

string

default: about:blank

title

required

Title

string

status

required

Status

integer

detail

required

Any of:

string

Example

{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Privacy Apache 2.0 getgeolens.com