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

> Discover why MuapiClient prioritizes x-api-key over Bearer tokens for stateless authentication. Understand the backend's simple API-key requirement for secure integrations.

- Repository: [Anil Chandra Naidu Matcha/Open-Generative-AI](https://github.com/Anil-matcha/Open-Generative-AI)
- Tags: best-practices
- Published: 2026-04-24

---

**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`](https://github.com/Anil-matcha/Open-Generative-AI/blob/main/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`](https://github.com/Anil-matcha/Open-Generative-AI/blob/main/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:

```javascript
// 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`](https://github.com/Anil-matcha/Open-Generative-AI/blob/main/src/lib/muapi.js), where the fetch configuration explicitly sets the custom header:

```javascript
// 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`](https://github.com/Anil-matcha/Open-Generative-AI/blob/main/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:

```javascript
// 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:

```javascript
// 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`](https://github.com/Anil-matcha/Open-Generative-AI/blob/main/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`](https://github.com/Anil-matcha/Open-Generative-AI/blob/main/src/lib/muapi.js) and [`packages/studio/src/muapi.js`](https://github.com/Anil-matcha/Open-Generative-AI/blob/main/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`](https://github.com/Anil-matcha/Open-Generative-AI/blob/main/src/lib/muapi.js) and [`packages/studio/src/muapi.js`](https://github.com/Anil-matcha/Open-Generative-AI/blob/main/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.