Authentication

Every request to the Mountaya developer platform carries an API key that identifies your organization and scopes what it may do. Most surfaces also require a short-lived session token. This page covers both, the query-parameter fallbacks for browser navigations, and how rate limiting surfaces.

API keys

Keys come in a pair. Choose which to use by where the request runs.

Scopes

Each key carries scopes that gate which products it can reach. Enable only what an integration needs.

Session tokens

A session token (sess_…) is a short-lived credential derived from your key pair. The Data API requires one on every request. Map Embedding requires one whenever your organization enables session enforcement (require_session_token); organizations without their own backend can leave it off and embed with just a publishable key and origin validation.

curl -X POST https://internal.mountaya.com/v1/sessions \
  -H "X-API-Key: sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"publishable_key": "pk_your_publishable_key"}'

{
  "data": {
    "token": "sess_…",
    "expires_at": "2026-06-03T12:05:00Z"
  }
}

curl https://data.mountaya.com/graphql \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __typename }"}'

OAuth for MCP connectors

The MCP server accepts a second, interactive authentication path built for AI assistants: instead of sending keys, you connect once over OAuth. The assistant discovers Mountaya's OAuth server from the connector URL and registers itself (no app to create), you sign in with your Mountaya account, and on a consent screen you choose which publishable key the assistant should act with. From then on the assistant carries an access token, scoped to that key's organization, and you never paste a key into its config. This is the path Claude, ChatGPT, and similar assistants use; see connect your assistant over OAuth for the full flow.

The same MCP endpoint also accepts the pk_/sk_ header pair for non-interactive clients. A client you script yourself can skip OAuth entirely and send a publishable key in X-API-Key and a secret key in X-Secret-Key on each request, and the server brokers a session token for it, exactly as the MCP server page documents. Use OAuth for an assistant a person signs into; use the key pair for an unattended client.

Query-parameter fallbacks

Some browser navigations, such as an <iframe src> or a download <a href>, cannot set custom headers. For those cases the publishable key and session token may travel as query parameters instead of headers:

• ?publishable_key=pk_… is accepted in place of the X-API-Key header.
• ?session_token=sess_… is accepted in place of the X-Session-Token header.

The header form always takes precedence when both are present.

Errors and rate limits

Each product documents the errors specific to its requests; this section covers the model shared across the platform.

Rate limiting

Limits are applied per key. When you exceed one, the API responds with 429 Too Many Requests and a Retry-After header giving the number of seconds to wait. Back off for that interval, then retry, ideally with exponential backoff if you retry repeatedly.

GraphQL errors

The Data API is GraphQL, so it answers with 200 OK even when a query fails and reports problems in an errors array. Each entry carries a human-readable message, the response path it applies to, and an extensions object with machine-readable detail such as an error code.

{
  "data": null,
  "errors": [
    {
      "message": "session token is required",
      "path": ["suggestions"],
      "extensions": { "code": "UNAUTHORIZED" }
    }
  ]
}

Inspect errors on every Data API response, not just the HTTP status. A partial result can return both data and errors together. Rate limiting still surfaces as a 429 with Retry-After at the transport layer, before a GraphQL response is produced.

Next steps