---
title: "Gateway contract overview"
description: "Understand authentication, greedy paths, explicit ProviderConnection resolution, streaming, metering, and errors before using the generated method pages."
---

> Documentation Index
> Fetch the complete documentation index at: https://nexus.microvoid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway contract overview

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:

```text
https://gateway.nexus.microvoid.io/providers/<providerConnectionId>
```

The SDK appends its complete path. For example:

```text
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/completions
```

`providerPath` 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`.

## Generated method pages

- [GET](/api-reference/gateway/operations/proxy-provider-get)
- [POST](/api-reference/gateway/operations/proxy-provider-post)
- [PUT](/api-reference/gateway/operations/proxy-provider-put)
- [PATCH](/api-reference/gateway/operations/proxy-provider-patch)
- [DELETE](/api-reference/gateway/operations/proxy-provider-delete)
- [HEAD](/api-reference/gateway/operations/proxy-provider-head)
- [OPTIONS](/api-reference/gateway/operations/proxy-provider-options)
- <a href="https://docs.nexus.example/api/openapi/gateway.openapi.json" download>
    Download Gateway OpenAPI
  </a>

Source: https://nexus.microvoid.io/api-reference/gateway/index.mdx