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.
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_atstring (date-time)
Timestamp of the publishable key's creation.
etagstring
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.
idstring (uuid)
Identifier of the key. It is what names the key on an update or a revocation, and is not the key itself.
keystring
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_atstring (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.
namestring
Display name of the publishable key.
organization_idstring (uuid)
Identifier of the organization the key belongs to.
revoked_atstring (date-time)
Timestamp of the key's revocation. Absent on a key still in force.
scopesarray of string
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.
/v1/organizations/{organization_id}/publishable-keysReturns 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
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a 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_atand stays in the listing, so an audit of what was once in circulation does not need a second source. scopekeeps 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
limitsays otherwise, most recently created first unlesssortsays otherwise. Send the page'snext_cursorback ascursorfor the next one; the last page reportsnext_cursor: null.
Path parameters
organization_idstring (uuid)
in path
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
cursorstring
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.
limitinteger (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.
scopestring
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.
sortstring
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.
extensionsobject
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.
dataarray of PublishableKey
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/publishable-keysCreates 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
managementcarries no other scope. Ascopeslist namingmanagementbeside another scope is a400and no key is created: the answer carries oneVALIDATION_FAILEDentry per scope listed besidemanagement, each naming that scope's position inscopes. It is asked before any scope's product, so such a list is never answered402. - A key carrying
studio-embeddedcarriestilesanddatabeside it, the scopes its editor's map and previews are requested under. Ascopeslist namingstudio-embeddedwithout one of them is a400and no key is created: the answer carries oneVALIDATION_FAILEDentry per missing scope, each namingscopes. Neither is added for the caller, and it is asked before any scope's product, so such a list is never answered402. - A scope can be granted only while the organization holds its product. Granting one it does not hold is a
402and no key is created: the answer carries one entry per refused scope, each naming that scope's position inscopes.publishingneeds Map Publishing,studio-embeddedneeds Embedded Studio and Map Studio, andtilesneeds the Tile API, each granted by the organization's agreement with Mountaya.dataandmcpneed 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.managementbelongs to no product and is never refused this way. - A key keeps a scope whose product is later switched off. The scope answers
402wherever 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_idstring (uuid)
in path
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-Keystring
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.
namestring
in body
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.
scopesarray of string
in body
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataPublishableKey
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.
Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.
/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
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a 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
ETagis the key'setag. Send it asIf-MatchonpatchOrganizationPublishableKeyordeleteOrganizationPublishableKeyto make the change conditional on nobody having changed the key since.
Path parameters
organization_idstring (uuid)
in path
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_idstring (uuid)
in path
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataPublishableKey
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.
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/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
managementcarries no other scope. Ascopeslist namingmanagementbeside another scope is a400and nothing is changed, the name included: the answer carries oneVALIDATION_FAILEDentry per scope listed besidemanagement, each naming that scope's position inscopes. It is asked whatever the key carries now, and before any scope's product, so such a list is never answered402. - A key carrying
studio-embeddedcarriestilesanddatabeside it, the scopes its editor's map and previews are requested under. Ascopeslist namingstudio-embeddedwithout one of them is a400and nothing is changed, the name included: the answer carries oneVALIDATION_FAILEDentry per missing scope, each namingscopes. 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 answered402. - 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
402and nothing is changed, the name included: the answer carries one entry per refused scope, each naming that scope's position inscopes. - 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
402wherever 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
scopeslist is a400namingscopes, 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
409and nothing is changed. If-Matchmakes the change conditional: send the key'setag, and a key changed since is refused with412, changing nothing.
Webhook events organization.publishable_key.updated, recorded by the task organization.publishable_key.update.
Path parameters
organization_idstring (uuid)
in path
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_idstring (uuid)
in path
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-Keystring
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-Matchstring
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.
namestring
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.
scopesarray 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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataPublishableKey
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.
Errors 400, 401, 402, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.
/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
getOrganizationPublishableKeyscarryingrevoked_at, and is never accepted again. - The answer is the revoked key, carrying
revoked_at, with itsETag. 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
reconnectevent whose reason iscredential-revoked. If-Matchmakes the revocation conditional: send the key'setag, and a key changed since is refused with412, revoking nothing.
Webhook events organization.publishable_key.revoked, recorded by the task organization.publishable_key.revoke.
Path parameters
organization_idstring (uuid)
in path
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_idstring (uuid)
in path
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-Keystring
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-Matchstring
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataPublishableKey
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.
Errors 400, 401, 403, 404, 409, 412, 429, 500, 504. See Errors.