Provider Proxy API

Forward provider-specific HTTP requests through GoodMem to reuse stored credentials and centralized access control. The proxy works with any registered embedder, reranker, or LLM resource.

Endpoint structure

/v1/proxy/{resource-type}/{resource-id}/{provider-path}

• {resource-type} — embedders, rerankers, or llms
• {resource-id} — UUID returned when the resource was registered with GoodMem
• {provider-path} — provider-specific suffix (for example v1/models or tokenize)

{provider-path} is appended to the inference target’s stored endpointUrl before the call is forwarded. Common scenarios include:

• Registered endpointUrl: https://api.openai.com/v1 → proxy call GET /v1/proxy/embedders/{id}/models forwards to https://api.openai.com/v1/models
• Registered endpointUrl: https://custom-vllm.com/inference → proxy call POST /v1/proxy/llms/{id}/v1/completions forwards to https://custom-vllm.com/inference/v1/completions

Query strings are appended unchanged.

HTTP methods and query strings pass through unchanged; the proxy simply streams the upstream response back to the caller.

The proxy does not rewrite payloads. Any provider-specific request or response formats must already be compatible with the target API.

Authentication and authorization

1. Clients present their GoodMem API key (x-api-key) instead of vendor credentials.
2. GoodMem authenticates the key, enforces READ_* visibility, and checks the proxy-specific permissions:
   • PROXY_INFERENCE_TARGET_ANY
   • PROXY_INFERENCE_TARGET_OWN
3. If authorized, the server retrieves the stored provider configuration and forwards the request.

Unauthorized calls return 401; calls lacking proxy permissions return 403 and are not forwarded to the provider.

Credential injection and forwarding

• The proxy removes the client-supplied x-api-key header and any existing Authorization header before forwarding.
• If the registered resource has stored credentials, the proxy injects Authorization: Bearer <stored-token> before sending the request upstream. Resources without stored credentials (for example, unauthenticated vLLM deployments) are forwarded without an Authorization header. Only Bearer-style secrets are injected in v1; other auth patterns still require calling the provider directly.
• Request and response bodies stream over Jetty’s non-blocking proxy, so large payloads and streaming responses work out of the box.
• Status codes and headers from the provider are preserved.
• Requests are audit logged the same way as other REST calls, and Micrometer metrics record request volume, latency, payload sizes, and upstream error rates.

Example requests

List OpenAI models through GoodMem:

curl \
  -H "x-api-key: gm_your_key" \
  https://api.goodmem.ai/v1/proxy/embedders/62a805e9-e539-4cb2-9d34-9482d8163437/v1/models

Call a custom tokenization endpoint:

curl \
  -H "x-api-key: gm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world"}' \
  https://api.goodmem.ai/v1/proxy/embedders/62a805e9-e539-4cb2-9d34-9482d8163437/tokenize

Forward a rerank operation:

curl \
  -H "x-api-key: gm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query":"lakes"}' \
  https://api.goodmem.ai/v1/proxy/rerankers/d08546f5-694b-4f5f-96cc-091d07437957/rerank

Operational limits

• Only Bearer-style secrets are injected in v1; other auth patterns require calling the provider directly.
• Provider responses (4xx/5xx) pass through unchanged.
• WebSockets are not proxied.
• Standard GoodMem rate limits apply to proxy traffic. Provider-side throttling also still applies.
• The proxy inherits the TLS requirements of the provider endpointUrl; certificate validation follows Jetty defaults.

Observability

• Prometheus counter goodmem.proxy.requests.total tracks request volume by resource type, HTTP method, status code, and provider type.
• Timer goodmem.proxy.request.duration measures end-to-end latency and is tagged with resource type, provider type, and status class.
• goodmem.proxy.auth_failures.total counts authentication or authorization failures before a request reaches the upstream provider.
• Payload sizes are recorded in goodmem.proxy.request.size.bytes and goodmem.proxy.response.size.bytes.
• Upstream 5xx responses increment goodmem.proxy.provider_errors.total with the resource ID and provider type.
• All requests are audit logged with the authenticated user, target resource, method, and upstream status.

Troubleshooting

Related links

• Server runtime footprint — networking, health probes, and monitoring endpoints.
• Source code: server/src/main/java/com/goodmem/proxy/
• Permission definitions: server/src/main/java/com/goodmem/security/Permission.java