Why MuapiClient Uses x-api-key Instead of Bearer Token Authentication

MuapiClient transmits the API key in a custom x-api-key HTTP header because the Muapi backend requires simple, stateless API-key authentication rather than OAuth-style Bearer tokens, as implemented in src/lib/muapi.js.

The Open-Generative-AI repository by Anil-matcha implements a specialized MuapiClient to communicate with the Muapi service. Unlike typical REST clients that rely on Authorization: Bearer <token> headers, this client deliberately uses a custom x-api-key header to authenticate every request, from image generation to file uploads.

How MuapiClient Implements the x-api-key Header

The client retrieves the API key from browser storage before attaching it to every outgoing request.

Retrieving the API Key

In src/lib/muapi.js, the getKey() method checks window.__MUAPI_KEY__ first, then falls back to localStorage.getItem('muapi_key') to obtain the user's secret key. Lines 9-13 implement this logic, throwing an error if neither source exists:

// src/lib/muapi.js
getKey() {
    const key = window.__MUAPI_KEY__ || localStorage.getItem('muapi_key');
    if (!key) throw new Error('API Key missing. Please set it in Settings.');
    return key;
}

Attaching Headers to Requests

For every API call—including generateImage—the client constructs a headers object containing 'x-api-key': key alongside Content-Type. This pattern appears at lines 75-78 in src/lib/muapi.js, where the fetch configuration explicitly sets the custom header:

// src/lib/muapi.js – generateImage()
const response = await fetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': key               // custom authentication header
    },
    body: JSON.stringify(finalPayload)
});

Why Bearer Tokens Aren't Used

The architecture reflects three deliberate design choices by the Muapi service maintainers.

Simplicity Over OAuth Flows

Muapi's public API avoids the complexity of authorization codes, token refresh cycles, and scoped permissions. A single static key eliminates client-side state management for token expiration, reducing implementation overhead for consumers of the Open-Generative-AI library.

Stateless Request Validation

The backend validates the x-api-key value on each request without maintaining server-side sessions. This aligns with REST principles where calls remain self-contained, allowing the Muapi service to scale horizontally without session affinity or distributed token stores.

Consistency Across All Endpoints

Whether generating images, polling status, or uploading files, every endpoint uses the identical x-api-key header. This uniformity simplifies the client code in both the main application and the Studio package, ensuring authentication logic remains identical for POST, GET, and multipart requests.

Implementation in the Studio Package

The Studio package (packages/studio/src/muapi.js) replicates this pattern. Helper functions like submitAndPoll() and uploadFile() receive the apiKey as an explicit argument and attach it via headers at lines 32-35:

// packages/studio/src/muapi.js – submitAndPoll()
const response = await fetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': key               // custom authentication header
    },
    body: JSON.stringify(payload)
});

Even file uploads using XMLHttpRequest set the header explicitly:

// packages/studio/src/muapi.js – uploadFile()
xhr.setRequestHeader('x-api-key', apiKey);

Summary

• MuapiClient uses x-api-key because the Muapi backend requires API-key authentication, not OAuth Bearer tokens.
• The key is retrieved from window.__MUAPI_KEY__ or localStorage via getKey() in src/lib/muapi.js.
• Every request includes the custom header, including file uploads in the Studio package.
• This approach prioritizes simplicity, statelessness, and endpoint consistency.

Frequently Asked Questions

Can I use a Bearer token with MuapiClient?

No. The Muapi service only recognizes the x-api-key header. Attempting to use Authorization: Bearer <token> will result in authentication failures because the backend logic specifically searches for the custom header value in src/lib/muapi.js and packages/studio/src/muapi.js.

Where is the API key stored in Open-Generative-AI?

The client checks window.__MUAPI_KEY__ first, then localStorage.getItem('muapi_key'). If neither exists, the getKey() method throws an error prompting the user to configure the key in Settings.

Does the Studio package use the same authentication method?

Yes. Both src/lib/muapi.js and packages/studio/src/muapi.js use identical x-api-key header patterns. The Studio helpers accept the key as a parameter and attach it to fetch and XMLHttpRequest objects at lines 30-35.

Why not use standard Authorization headers for API keys?

While some services place API keys in Authorization: ApiKey <key>, Muapi standardized on the non-standard x-api-key header. This design choice eliminates parsing ambiguity and keeps the implementation distinct from OAuth workflows, as reflected throughout the Anil-matcha/Open-Generative-AI codebase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}