Authentication

Two keys. Which one to use, and where each belongs.

Every Miso request carries an API key. Which key you use decides what the request can reach, so start here before you write any integration code.

You get two keys per environment:

The secret key trusts the caller completely, so it never leaves your back end. The publishable key travels to the browser, so Miso limits what it can do.

Which hostname? Browser code calls https://api-edge.askmiso.com, which is behind a CDN. Server code calls https://api.askmiso.com. Both take the same keys. See Two hostnames.

API Keys

Miso uses API keys to authenticate requests. You can view and manage your API keys in the Dojo Dashboard.

Each environment has its own set of keys: one secret key and one publishable key. Pass the appropriate key with every API request.

Environments

There are three environments in Miso:

• Playground — A read-only tutorial environment pre-loaded with sample data. Use this to explore Miso's APIs without affecting your own data.
• Development — For staging, QA, and experimentation. Use this environment to test your integration before going live.
• Production — Your live environment. Use this for all requests that serve real users.

Secret API Key

The secret API key grants full access to all Miso API endpoints, including data ingestion and engine queries.

Keep this key private. Never expose it in client-side code or public repositories. If the key is compromised, revoke it in the Dojo Dashboard and generate a new one.

You can pass the secret key in either of two ways:

As a request header:

X-API-KEY: YOUR_SECRET_KEY

As a query parameter:

GET /v1/recommendation/user_to_products?api_key=YOUR_SECRET_KEY

Publishable API Key

The publishable API key is intended for use in front-end code (for example, browser JavaScript). Use it to stream interactions from the browser, and to retrieve read-only search, recommendation and answer results.

Most of what it reaches works for a signed-out visitor, on an anonymous_id.

You prove who the reader is only when the request claims a user_id. Send a signed JWT for that. The reader's own history, under /v1/ask/user_history/…, always needs one.

Below is the signed-in path. A signed-out visitor skips steps 1 to 3 and sends the publishable key on its own.

%%{init: {'theme':'base','themeVariables':{
'fontFamily':'IBM Plex Sans, ui-sans-serif, system-ui','fontSize':'14px',
'actorBkg':'#3148be','actorBorder':'#3148be','actorTextColor':'#ffffff',
'actorLineColor':'#9aa3c0','signalColor':'#9aa3c0','signalTextColor':'#6b7392',
'labelBoxBkgColor':'#f4effc','labelBoxBorderColor':'#cdbcf0',
'labelTextColor':'#40277a','noteBkgColor':'#e8ecfb','noteBorderColor':'#b9c2ea',
'noteTextColor':'#22307a','sequenceNumberColor':'#ffffff'
}}}%%
sequenceDiagram
    autonumber
    participant B as Browser
    participant S as Your server
    participant M as Miso

    B->>S: the reader signs in
    S->>S: sign a short-lived JWT with your secret key
    S-->>B: publishable key plus that JWT
    B->>M: API call with both
    M->>M: verify the JWT
    M-->>B: only this reader's data
    Note over S,M: the secret key never leaves your server

Pass the publishable key as a query parameter:

POST /v1/interactions?api_key=YOUR_PUBLISHABLE_KEY

Next

• API Overview — conventions shared by every endpoint.
• Errors & Rate Limits — what a 401 and a 403 mean here.
• User History — the browser flow, with a signed JWT.