Authentication and API keys

Every request through Maple Proxy is made with a Maple API key. Usage is billed to the account that owns the key.

Create an API key

In the Maple app, open Settings, then API & credits, then API Keys, and create a key. The full key is shown only once, so copy it somewhere safe. Existing keys can’t be revealed again; create a new key if you lose one.

The desktop app’s Local Proxy can create a key for itself when you first start it.

How the proxy picks a key

For each request, the proxy uses the first of these that applies:

1. The request’s own key. An Authorization: Bearer <key> header.
2. The saved default key. MAPLE_API_KEY (or --default-api-key), but only when CORS is turned off.

If neither applies, the proxy answers 401 without contacting Maple:

{
  "error": {
    "message": "No API key provided. Set MAPLE_API_KEY environment variable or provide Authorization header",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

The header must start with exactly Bearer (capital B, one space). A header in any other form is ignored and the saved default key is used instead, if there is one.

OpenAI client libraries send the api_key you give them as a bearer header. So when you use a saved default key, the client still needs some value. Any placeholder works, but a real key always wins over the default.

Where the key goes

The proxy keeps one shared, attested session with the Maple enclave. Each request’s API key is placed inside that request’s encrypted envelope. It is never forwarded as a plain Authorization header, it isn’t stored as shared client state, and it isn’t written to the proxy’s logs.

Saved key or per-request keys?

Public and shared deployments

When the proxy can be reached by people or code you don’t fully trust:

• Don’t set MAPLE_API_KEY. Anyone who can reach the proxy could spend it.
• Require each client to send its own key:

from openai import OpenAI

client = OpenAI(
    base_url="https://your-proxy.example.com/v1",
    api_key="user-specific-maple-api-key",  # each user provides their own key
)

• Review the proxy’s network exposure and logs before you treat the deployment as safe.

Browser clients and CORS

Browsers block web pages from calling the proxy unless you turn on CORS (MAPLE_ENABLE_CORS=true or --enable-cors). With CORS on:

• Any website can call the proxy from a visitor’s browser.
• The saved default key is ignored, even if it is set. Requests without their own Authorization header get 401.

This keeps a browser-reachable proxy from spending a key that a page didn’t supply. The Docker image turns CORS on by default.

Keep keys safe

• Treat API keys like passwords. Never commit them to version control.
• Prefer the MAPLE_API_KEY environment variable or a secrets manager over the --default-api-key flag, which can show up in process listings.
• Give each tool or user its own key, so you can revoke one without breaking the others.
• If a key leaks, delete it in Settings → API & credits → API Keys and create a new one.