Sessions
Exchange a secret key for a short-lived session token, naming the publishable key the session is bound to and, for a page that acts as a member, the user it acts as. A session token is what a browser surface authenticates with, and what decides whether a read is served the draft or the published snapshot; the secret key that minted it never reaches the page. There is no refresh operation: a session lives at most five minutes and a client mints a fresh one.
A short-lived session, minted by exchanging a secret key for one and bound to the publishable key named in the request, to the surface named there, and to the user named there, if any. Its sess_ token is what a browser surface authenticates with, what decides whether a read is served the draft or the published snapshot, and, when it names a user, what lets a request act as that member.
expires_atstring (date-time)
When the token stops being accepted: at most five minutes after the request, and sooner when postSession returned a token it minted moments earlier for the same publishable key, surface and user. There is no refresh operation: a new one is minted from the caller's own backend before this passes. Read this field rather than assuming the five minutes, so a client never holds a token past its end.
user_idstring (uuid) | null
The user the token names, the user_id the request asked for, or null for a token minted without one. A token naming a user is what lets a request act as that user: every operation whose x-acting-user is required refuses a token that names none with a 401. A token naming none writes nothing and reads what the publishable key alone does, the published snapshot and public-only listings; one minted for api also makes the management reads, and one minted for studio-embedded does not.
tokenstring
The session token. Send it back verbatim in X-Session-Token. It is OPAQUE to a client: the sess_ prefix is the only part of it this contract fixes for one. Do not parse it, do not derive an expiry from it, and read expires_at beside it instead. Mountaya's own SDKs read the surface it was minted for from it, so an Embedded Studio refuses a token minted for another surface before it sends anything.
/v1/sessionsCreates a short-lived session token by exchanging a secret key and a publishable key. The X-API-Key header with an sk_ value is required to authenticate this request. The token accompanies the publishable key it is minted against: every Data API request, every management operation and every studio-embedded operation require one beside the key.
Body
The publishable key the session token is minted against, and the user it names, where it names one.
publishable_keystring
in body
The publishable key value to bind the session to. Always the pk_ prefix followed by 32 lowercase hexadecimal characters, 35 in all, the shape every key is minted with.
user_idstring (uuid)
in body
The user the session acts as, which your backend asserts: a member of the publishable key's organization, or a user whose invitation to it is still pending, matched by an address the user's account has verified. The token is signed with it, and every operation whose x-acting-user is required acts as the user the token names, so a page holding the token acts as this user and nobody else. A management read under the token is answered only while this user holds the role that read asks of a member of the organization. The session governs the members with at most an admin's say, whoever it names: a session naming the owner is answered as an admin's on the owner's own acts, which are made only signed in to Mountaya's web application. A user who is neither a member nor invited answers 403, the same answer whether or not the user exists, and nothing is minted.
surfacestring
in body
One of: api, mcp, studio-embedded
The surface the session is minted for, which it keeps for its whole life. Omitted, it is api, the surface of your own clients.
Response 200
The session token, the user it names, and its expiry. Send the token in X-Session-Token beside the publishable key it was minted against. It may be a token minted moments earlier for the same key, surface and user, returned again with less of its lifetime left.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataSession
A short-lived session, minted by exchanging a secret key for one and bound to the publishable key named in the request, to the surface named there, and to the user named there, if any. Its sess_ token is what a browser surface authenticates with, what decides whether a read is served the draft or the published snapshot, and, when it names a user, what lets a request act as that member.
See the Session object.
Errors 400, 401, 402, 403, 404, 413, 429, 500, 504. See Errors.