Get started
Organization

API Keys

API Keys

The publishable keys an organization issues: what each one is called, which scopes it carries, and when it was last used. A publishable key is meant to be seen, so its value is returned in full on every read. Every operation here needs a session token beside the key.

The PublishableKey object

A publishable key: the credential a browser presents. It is safe to ship in a page, which is why what it reaches is narrowed by its scopes and why a management scope is never enough on its own.

created_at

string (date-time)

required

Timestamp of the publishable key's creation.

etag

string

required

The version of the key, the one the ETag of a read of it carries, opaque and compared whole. It moves on every change to the key's name or scopes and when it is revoked. Send it as If-Match to make patchOrganizationPublishableKey or deleteOrganizationPublishableKey conditional.

id

string (uuid)

required

Identifier of the key. It is what names the key on an update or a revocation, and is not the key itself.

key

string

required

The key value, the pk_ token a client sends as X-API-Key. Always the pk_ prefix followed by 32 lowercase hexadecimal characters, 35 in all, the shape every key is minted with. It is returned in full on every read, because a publishable key is meant to be seen.

last_used_at

string (date-time)

Timestamp of the last request that presented this key, recorded at most once a minute, so it may trail the latest use by up to a minute. Absent on a key never used.

name

string

required

Display name of the publishable key.

organization_id

string (uuid)

required

Identifier of the organization the key belongs to.

revoked_at

string (date-time)

Timestamp of the key's revocation. Absent on a key still in force.

scopes

array of string

required

The scopes the key carries, each at most once, in the order PublishableKeyScope declares them whatever order they were sent in. A key in force carries at least one, and one carrying management carries no other. A revoked key lists what it carried when it was revoked, which can be none. The list is what the key was given and nothing more, so no scope appears because another is present. A scope stays listed when its product is later switched off for the organization, and answers 402 where it is used until the product returns.

List an organization's publishable keys

GET
/v1/organizations/{organization_id}/publishable-keys

Returns the publishable keys the organization holds, revoked ones included, each with its scopes, when it was created and when a request last presented it. The key value itself is returned in full: a publishable key is meant to be seen, which is what distinguishes it from the secret key that mints sessions.

  • A session token minted for api without a user is asked for no member role on this read; one minted for studio-embedded without a user is the 401 a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise. Creating, changing and revoking keys take the same role, held by the user the session token names, which a write requires.
  • A revoked key carries revoked_at and stays in the listing, so an audit of what was once in circulation does not need a second source.
  • scope keeps the keys given that scope, revoked ones included.
  • The listing is paged. Nothing caps how many keys an organization mints, so a page holds 50 keys unless limit says otherwise, most recently created first unless sort says otherwise. Send the page's next_cursor back as cursor for the next one; the last page reports next_cursor: null.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Query parameters

cursor

string

in query

Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.

limit

integer (int32)

in query

default: 50

How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.

scope

string

in query

One of: publishing, studio-embedded, tiles, data, mcp, management

Keep only the keys given this scope. It reads the scopes a key carries, not the ones they include, so a key carrying studio-embedded, tiles and data is not kept for publishing.

sort

string

in query

default: -created_at

One of: -created_at, created_at, name, -name

The order of the listing, by one field: created_at or name, ascending, or either with a leading -, descending. Omitted, it is -created_at, the most recently created first. Publishable keys that tie on the field are ordered by id.

Response 200

One page of the organization's publishable keys, revoked ones included, in the order sort names. extensions.metadata.pagination.next_cursor asks for the next page, and is null on the last.

extensions

object

required

The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at, and the next_cursor of the page after it, null on the last.

data

array of PublishableKey

required

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

curl -s https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/publishable-keys \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": [
    {
      "id": "3b1f9c02-6d4e-4a87-b5c1-70e2af3d8916",
      "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
      "name": "Website embed",
      "key": "pk_9f3c2a71b845d0e4c7a6b3f180d92e5a",
      "created_at": "2026-02-03T11:45:02Z",
      "etag": "\"d3\"",
      "last_used_at": "2026-08-22T18:07:44Z",
      "scopes": [
        "publishing"
      ]
    }
  ],
  "extensions": {
    "metadata": {
      "pagination": {
        "limit": 50,
        "next_cursor": "eyJ2IjoxLCJzIjoiLXVwZGF0ZWRfYXQifQ"
      }
    }
  }
}

Create a publishable key

POST
/v1/organizations/{organization_id}/publishable-keys

Creates a publishable key with exactly the scopes the request names: none is added because another is present. Both the name and the scopes are required, and an empty scopes list is a 400 naming scopes: a key with no scopes reaches nothing, so there is no useful default to fall back on. The key value is returned here and on every later read, so nothing is lost by not recording it now. A create sent twice without an Idempotency-Key makes two keys; with one, the second is answered the first one's key. A create sent again with it, after the first failed with a 5xx once the key was made, is the 409 coded IDEMPOTENCY_ANSWER_UNAVAILABLE, whose extensions.metadata.location names the key made, /v1/organizations/{organization_id}/publishable-keys/{key_id}, so carry on with that one rather than creating it again.

  • Owner or admin only (403 otherwise).
  • A key carrying management carries no other scope. A scopes list naming management beside another scope is a 400 and no key is created: the answer carries one VALIDATION_FAILED entry per scope listed beside management, each naming that scope's position in scopes. It is asked before any scope's product, so such a list is never answered 402.
  • A key carrying studio-embedded carries tiles and data beside it, the scopes its editor's map and previews are requested under. A scopes list naming studio-embedded without one of them is a 400 and no key is created: the answer carries one VALIDATION_FAILED entry per missing scope, each naming scopes. Neither is added for the caller, and it is asked before any scope's product, so such a list is never answered 402.
  • A scope can be granted only while the organization holds its product. Granting one it does not hold is a 402 and no key is created: the answer carries one entry per refused scope, each naming that scope's position in scopes. publishing needs Map Publishing, studio-embedded needs Embedded Studio and Map Studio, and tiles needs the Tile API, each granted by the organization's agreement with Mountaya. data and mcp need the Data API, which the organization holds once its first card has opened its Data API subscription, or by its agreement, so they are refused before that. management belongs to no product and is never refused this way.
  • A key keeps a scope whose product is later switched off. The scope answers 402 wherever a request uses it, and works again once the product returns.

Webhook events organization.publishable_key.created, recorded by the task organization.publishable_key.create.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Body

What the key is for, and the scopes it carries.

name

string

in body

required

Display name of the publishable key: 2 to 30 characters as sent, and still at least 2 once leading and trailing whitespace is trimmed, which is the form it is stored in. A name is one line: a tab, a line break or a line separator between two of its characters is a 400, and one at either end is trimmed with the whitespace there.

scopes

array of string

in body

required

The scopes to give the key, each at most once. A key carries at least one: an empty list is a 400 naming scopes. A scope is granted only while the organization holds its product, so one it does not hold is a 402 naming its position in the list. management is carried alone: a list naming it beside another scope is a 400 naming the position of each scope beside it. studio-embedded is carried with tiles and data: a list naming it without one of them is a 400 naming scopes, once per missing scope.

Response 201

The key as created, including the pk_ value to send as X-API-Key. Location names it, /v1/organizations/{organization_id}/publishable-keys/{key_id}, the path getOrganizationPublishableKey reads it at.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

PublishableKey

required

A publishable key: the credential a browser presents. It is safe to ship in a page, which is why what it reaches is narrowed by its scopes and why a management scope is never enough on its own.

See the PublishableKey object.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.

curl -s -X POST https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/publishable-keys \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website embed",
    "scopes": ["publishing"]
  }'
201
Response
{
  "data": {
    "id": "3b1f9c02-6d4e-4a87-b5c1-70e2af3d8916",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Website embed",
    "key": "pk_9f3c2a71b845d0e4c7a6b3f180d92e5a",
    "created_at": "2026-02-03T11:45:02Z",
    "etag": "\"d3\"",
    "last_used_at": "2026-08-22T18:07:44Z",
    "scopes": [
      "publishing"
    ]
  }
}

Retrieve a publishable key

GET
/v1/organizations/{organization_id}/publishable-keys/{key_id}

Returns one of the organization's publishable keys, as getOrganizationPublishableKeys lists it: its scopes, when it was created, when a request last presented it, and revoked_at once it is revoked. A revoked key is still returned, so the key a Location or an audit names can always be read back. The key value itself is returned in full, as on every read.

  • A session token minted for api without a user is asked for no member role on this read; one minted for studio-embedded without a user is the 401 a key alone gets. One that names a user is answered only while that user holds the owner or admin role in the organization, and is a 403 otherwise.
  • The answer's ETag is the key's etag. Send it as If-Match on patchOrganizationPublishableKey or deleteOrganizationPublishableKey to make the change conditional on nobody having changed the key since.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

key_id

string (uuid)

in path

required

Identifier of the publishable key the operation acts on. It is the key's id, not the pk_ value the key itself is.

Response 200

The key, revoked or not, with the scopes it carries.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

PublishableKey

required

A publishable key: the credential a browser presents. It is safe to ship in a page, which is why what it reaches is narrowed by its scopes and why a management scope is never enough on its own.

See the PublishableKey object.

Errors 400, 401, 403, 404, 429, 500, 504. See Errors.

curl -s https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/publishable-keys/3b1f9c02-6d4e-4a87-b5c1-70e2af3d8916 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": {
    "id": "3b1f9c02-6d4e-4a87-b5c1-70e2af3d8916",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Website embed",
    "key": "pk_9f3c2a71b845d0e4c7a6b3f180d92e5a",
    "created_at": "2026-02-03T11:45:02Z",
    "etag": "\"d3\"",
    "last_used_at": "2026-08-22T18:07:44Z",
    "scopes": [
      "publishing"
    ]
  }
}

Update a publishable key's name or scopes

PATCH
/v1/organizations/{organization_id}/publishable-keys/{key_id}

Changes what a key is called, what it reaches, or both. Each field is optional and an omitted one is left alone, but scopes is replaced whole rather than merged: a request that sends it lists every scope the key is to keep, and a scope left out is removed. Mountaya answers the key's next request by its new scopes, so a page still holding it starts getting 403 on what it stops reaching. An answer a shared cache already holds for the key is served from there until its lifetime runs out: at most 5 minutes for a public tile, 6 for a published itinerary read or its pace (max-age=300 and stale-while-revalidate=60), and 25 hours for the layer catalog (max-age=86400 and stale-while-revalidate=3600).

  • Owner or admin only (403 otherwise).
  • A key carrying management carries no other scope. A scopes list naming management beside another scope is a 400 and nothing is changed, the name included: the answer carries one VALIDATION_FAILED entry per scope listed beside management, each naming that scope's position in scopes. It is asked whatever the key carries now, and before any scope's product, so such a list is never answered 402.
  • A key carrying studio-embedded carries tiles and data beside it, the scopes its editor's map and previews are requested under. A scopes list naming studio-embedded without one of them is a 400 and nothing is changed, the name included: the answer carries one VALIDATION_FAILED entry per missing scope, each naming scopes. Neither is added for the caller, it is asked whatever the key carries now, and before any scope's product, so such a list is never answered 402.
  • A scope the key does not already carry can be granted only while the organization holds its product. Granting one it does not hold is a 402 and nothing is changed, the name included: the answer carries one entry per refused scope, each naming that scope's position in scopes.
  • A scope the key already carries is kept even when its product has since been switched off, so sending a key its own list back is never refused. Such a scope answers 402 wherever a request uses it, until the product returns.
  • The key is given exactly the list sent: none is added because another is present.
  • An empty scopes list is a 400 naming scopes, as it is on creation: a key carries at least one scope.
  • The pk_ value never changes. Replacing a key that has leaked is revoking it and creating another.
  • A revoked key cannot be changed: the request is a 409 and nothing is changed.
  • If-Match makes the change conditional: send the key's etag, and a key changed since is refused with 412, changing nothing.

Webhook events organization.publishable_key.updated, recorded by the task organization.publishable_key.update.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

key_id

string (uuid)

in path

required

Identifier of the publishable key the operation acts on. It is the key's id, not the pk_ value the key itself is.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

If-Match

string

in header

Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.

Body

The name to give the key, the scopes to replace its own with, or both.

name

string

in body

Display name of the publishable key. Omit to keep the current value. When sent, it is 2 to 30 characters as sent, and still at least 2 once leading and trailing whitespace is trimmed, which is the form it is stored in. A name is one line: a tab, a line break or a line separator between two of its characters is a 400, and one at either end is trimmed with the whitespace there.

scopes

array of string

in body

The scopes the key carries from now on, each at most once, replacing the list it held. Omit to keep the current scopes. A key carries at least one: an empty list is a 400 naming scopes. A scope the key does not already carry is granted only while the organization holds its product, so one it does not hold is a 402 naming its position in the list; a scope the key already carries is kept whatever has become of its product. management is carried alone: a list naming it beside another scope is a 400 naming the position of each scope beside it. studio-embedded is carried with tiles and data: a list naming it without one of them is a 400 naming scopes, once per missing scope, whatever the key carries now.

Response 200

The key after the change, in full.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

PublishableKey

required

A publishable key: the credential a browser presents. It is safe to ship in a page, which is why what it reaches is narrowed by its scopes and why a management scope is never enough on its own.

See the PublishableKey object.

Errors 400, 401, 402, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.

curl -s -X PATCH https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/publishable-keys/3b1f9c02-6d4e-4a87-b5c1-70e2af3d8916 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["tiles"]}'
200
Response
{
  "data": {
    "id": "3b1f9c02-6d4e-4a87-b5c1-70e2af3d8916",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Website embed",
    "key": "pk_9f3c2a71b845d0e4c7a6b3f180d92e5a",
    "created_at": "2026-02-03T11:45:02Z",
    "etag": "\"d3\"",
    "last_used_at": "2026-08-22T18:07:44Z",
    "scopes": [
      "publishing"
    ]
  }
}

Revoke a publishable key

DELETE
/v1/organizations/{organization_id}/publishable-keys/{key_id}

Revokes a publishable key. Mountaya answers every client still presenting it with a 401 from its next request, so revoke a key that has leaked and create its replacement first if the surface using it cannot go dark. An answer a shared cache already holds for the key is served from there until its lifetime runs out, which no revocation shortens: at most 5 minutes for a public tile, 6 for a published itinerary read or its pace, and 25 hours for the layer catalog, as each of those reads states in its Cache-Control.

  • Owner or admin only (403 otherwise).
  • It cannot be undone. A revoked key stays in getOrganizationPublishableKeys carrying revoked_at, and is never accepted again.
  • The answer is the revoked key, carrying revoked_at, with its ETag. Revoking a key already revoked changes nothing and answers 200 again with the key as it stands, so a revocation is safe to repeat.
  • Revoking the key a session was minted against ends that session too: a session token names the key it was issued for, and a stream opened with it ends with a reconnect event whose reason is credential-revoked.
  • If-Match makes the revocation conditional: send the key's etag, and a key changed since is refused with 412, revoking nothing.

Webhook events organization.publishable_key.revoked, recorded by the task organization.publishable_key.revoke.

Path parameters

organization_id

string (uuid)

in path

required

Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.

key_id

string (uuid)

in path

required

Identifier of the publishable key the operation acts on. It is the key's id, not the pk_ value the key itself is.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

If-Match

string

in header

Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.

Response 200

The key, revoked by this request or an earlier one, carrying revoked_at; ETag carries its etag. It stays in getOrganizationPublishableKeys as it is here, and is never accepted again.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

PublishableKey

required

A publishable key: the credential a browser presents. It is safe to ship in a page, which is why what it reaches is narrowed by its scopes and why a management scope is never enough on its own.

See the PublishableKey object.

Errors 400, 401, 403, 404, 409, 412, 429, 500, 504. See Errors.

curl -s -X DELETE https://api.mountaya.com/v1/organizations/d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b/publishable-keys/3b1f9c02-6d4e-4a87-b5c1-70e2af3d8916 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": {
    "id": "3b1f9c02-6d4e-4a87-b5c1-70e2af3d8916",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Website embed",
    "key": "pk_9f3c2a71b845d0e4c7a6b3f180d92e5a",
    "created_at": "2026-02-03T11:45:02Z",
    "etag": "\"d3\"",
    "last_used_at": "2026-08-22T18:07:44Z",
    "scopes": [
      "publishing"
    ]
  }
}