Authentication

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 rule behind the split is short. 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.

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). It can be used to stream interactions from the browser or to retrieve read-only search and recommendation results for a given user.

%%{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

Important: When you use the publishable API key, hash the user_id field in your requests to maintain security compliance.

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.