OpenAPI has no standard greedy path template. The generated pages describe seven concrete HTTP methods, while this overview defines the shared ANY /providers/{providerConnectionId}/{providerPath...} behavior.
Gateway authentication
Send the Nexus Inference Key in Authorization: Bearer <inference-key>. The Key resolves ApiKeyBinding → WorkspaceAccess → Workspace; a valid Management Key is still rejected by the data plane.
The Gateway consumes that Authorization value. It never forwards it to the Provider and instead applies the encrypted credential stored on the selected ProviderConnection.
Base URL and greedy provider path
Configure a provider-compatible SDK with this Base URL:
https://gateway.nexus.microvoid.io/providers/<providerConnectionId>The SDK appends its complete path. For example:
Gateway origin
https://gateway.nexus.microvoid.io
+ providerConnectionId
/providers/533c4e1e-2823-4349-86b9-d6f1a869a2ca
+ provider path
/chat/completions
→ Nexus request
https://gateway.nexus.microvoid.io/providers/533c4e1e-2823-4349-86b9-d6f1a869a2ca/chat/completions
+ Workspace-scoped ProviderConnection baseUrl
https://openrouter.ai/api/v1
→ upstream target
https://openrouter.ai/api/v1/chat/completionsproviderPath represents the entire remaining suffix, including / characters. Nexus safely appends it without allowing an absolute URL, directory traversal, encoded bypass, or request-level Host override.
ProviderConnection resolution
The Inference Key determines the Workspace. The UUID in the Base URL selects exactly one ACTIVE connection using (workspaceId, providerConnectionId). A UUID from another Workspace cannot match, and clients cannot supply an arbitrary upstream Host.
Nexus does not choose a connection by model name and does not alter the Provider’s model identifier.
Request and response passthrough
The Gateway preserves the provider path, query string, HTTP method, Content-Type, and body. Provider payloads remain opaque.
It removes Host, Content-Length, cookies, hop-by-hop headers, and Nexus-internal headers. It replaces client Authorization with the stored Provider credential. Upstream status, body, supported response headers, Content-Type, SSE, and binary streams are returned without reshaping the provider payload.
Metering support
Transport support and metering support are separate. Token quota requires a matching Usage Inspector. An endpoint without one is rejected with the stable metering_unsupported error unless the Workspace explicitly permits unmetered passthrough.
Quota is reserved in PostgreSQL before the Provider call. Completion, Provider error, and client cancellation each enter one idempotent settle-or-release terminal path.
Streaming and cancellation
SSE is forwarded without buffering. Supported inspectors observe Usage and finish semantics without rewriting provider events. Client cancellation propagates upstream and still closes the reservation exactly once.
Nexus response headers
Successful responses can include:
| Header | Meaning |
|---|---|
x-nexus-request-id |
Stable identifier for request, Invocation, Usage, and diagnostics. |
x-nexus-metering-status |
metered or explicitly permitted unmetered. |
x-nexus-quota-remaining |
Remaining quota units when Workspace policy exposes them. |
x-nexus-quota-reset |
Current period reset time. |
Error semantics
| Status | Contract meaning |
|---|---|
400 |
Unsafe path/header or invalid proxy request. |
401 |
Inference Key is invalid or expired. |
403 |
WorkspaceAccess is unavailable or connection use is denied. |
404 |
No ACTIVE connection with this UUID exists in the authenticated Workspace. |
409 |
Metering is unsupported and unmetered passthrough is not enabled. |
429 |
Quota is insufficient before Provider invocation. |
502 |
Connection or upstream Provider failure. |
Errors use the stable JSON envelope defined by the Gateway OpenAPI document. Do not infer whether the Provider was called from status alone; use the error code and x-nexus-request-id.