Endpoints and Authentication

The RawClient constructor requires the Catalog Service Base URL and an MOI API Key. The SDK normalizes the URL, removes a trailing slash, and automatically sends this header on every request:

moi-key: <API_KEY>

This is not the Authorization: Bearer scheme used by the Genesis model API. Do not interchange the endpoints or credentials, even if both are available in the same deployment.

Prepare environment variables

Obtain the actual values from the target MOI environment’s administration entry point or deployment administrator:

export MOI_BASE_URL="https://<catalog-service-host>"
export MOI_API_KEY="<MOI API Key>"

The Base URL must include http:// or https:// and a host. Do not put query parameters or a fragment in it; both SDKs discard those parts during initialization. Surrounding whitespace is removed from the API Key, and an empty value causes client construction to fail.

Keep the Key in server-side environment variables or a secret manager. Never embed it in browser code, mobile packages, container images, or Git, and never print it in logs.

Let the SDK create the authentication header

Python:

import os
from moi import RawClient

client = RawClient(
    os.environ["MOI_BASE_URL"],
    os.environ["MOI_API_KEY"],
)
print(client.health_check())

Go:

client, err := sdk.NewRawClient(
	os.Getenv("MOI_BASE_URL"),
	os.Getenv("MOI_API_KEY"),
)
if err != nil {
	log.Fatal(err)
}

status, err := client.HealthCheck(ctx)
if err != nil {
	log.Fatal(err)
}
fmt.Println(status)

Do not override moi-key through WithHeader / with_header. To attach a traceable business request ID to one call, use the dedicated option:

from moi.options import with_request_id

catalogs = client.list_catalogs(with_request_id("catalog-list-001"))

catalogs, err := client.ListCatalogs(
	ctx,
	sdk.WithRequestID("catalog-list-001"),
)

It is sent as X-Request-ID and can be correlated with service logs. It is not an authentication value.

Call as a different identity

Python’s with_special_user(api_key) and Go’s WithSpecialUser(apiKey) create a client with a different Key while reusing the existing underlying HTTP client. The original client’s Key is unchanged:

user_client = client.with_special_user(os.environ["MOI_OTHER_API_KEY"])

userClient := client.WithSpecialUser(os.Getenv("MOI_OTHER_API_KEY"))

Use this only when the application legitimately needs to act as another authorized identity. Never accept arbitrary end-user input as a Key, and do not mutate identity on a shared client between concurrent requests. The Go method panics for an empty Key, so validate configuration first; the Python method raises ValueError.

Diagnose authentication failures

Check these points in order:

  1. The Base URL belongs to the intended environment and is reachable from the application network.

  2. The Key is complete, valid, and issued for the same environment.

  3. The calling identity has permission for the target resource and operation.

  4. The SDK-generated moi-key remains present and an intermediary has not removed custom headers.

  5. Record X-Request-ID and the HTTP status, business code, and request_id from SDK errors—but never the Key.

Network failures and non-2xx responses produce HTTP errors. A successful HTTP response whose envelope code does not indicate success produces an API business error. The Go SDK compares OK case-insensitively; the Python SDK currently requires a non-empty code to equal OK exactly. See Results, Pagination, and Streaming for response and error structures.