# Variants

> Field reference for Surface Variants and override settings: named surface variations selectable at request time.
A Surface Variant is a named, switchable snapshot of an Agent Surface stored as a sparse delta over the base surface. Variants are selected at request time by appending $alias to the surface route.

```text
https:///$/
```

When no $alias is present, the gateway uses the default variant (the base surface, unless a Default Variant is set in the surface settings).

## Variant fields

| Field | Type | Required | Default | Description |
| Variant ID | string (UUID) | Yes | — | Stable internal identifier. Survives renames of alias and name. Referenced by the Default Variant setting on the surface. |
| Alias | string | Yes | — | URL-safe alias used in the route path. Must match ^[a-z0-9-]{1,32}$ (lowercase letters, digits, dashes; max 32 characters). Must be unique within the surface. |
| Name | string | Yes | — | Human-readable name shown in the dashboard. |
| Description | string | No | "" | Free-text description. |
| Enabled | bool | No | true | Whether this variant accepts traffic. A disabled variant returns HTTP 503, not 404, so callers can distinguish “intentionally off” from “does not exist”. |
| Overrides | [Override settings](#override-settings) | No | Empty | Sparse or complete delta applied over the base surface at resolve time. |

### Alias grammar

The alias must satisfy ^[a-z0-9-]{1,32}$:

- Lowercase ASCII letters, digits, and dashes.

- No underscores, dots, or uppercase.

- Between 1 and 32 characters.

- Must be unique across all variants on the same surface.

Validation is enforced server-side. Malformed aliases are rejected on create and update.

### Lifecycle states

| Status | Request behaviour |
| Active (enabled: true) | Variant is active and serves traffic. |
| Disabled (enabled: false) | Variant exists but returns HTTP 503. Useful for temporarily disabling a variant without deleting it. |

## Override settings

The Overrides configuration holds a delta applied over the base surface at variant resolution time. Two merge modes are available: sparse merge (default) and complete snapshot.

| Field | Type | Required | Default | Description |
| Override mode | toggle | No | Sparse merge | Merge mode selector. See [Merge modes](#merge-modes). |
| Access Point | AccessPointOverrides | No | None | Access point delta. Cannot override Listener address, Channel Route, or Protocol; these are surface-level identifiers. |
| Managed Agent | TargetOverrides | No | None | Target delta. |
| Outbound Listener | TransitOverrides | No | None | Transit delta. |
| Agent Identity | SurfaceIdentitySlots | No | None | Per-variant identity slot bindings. When set, replaces the base surface’s identity slots wholesale. Slots are independent per variant, so rotating a credential in one variant does not affect others. |
| Credential Delegation | OutboundCredentialBinding[] | No | None | Per-variant outbound credential bindings. When set, replaces the base surface’s credential delegation list wholesale. |

### Merge modes

#### Sparse merge (default)

A field with no value set on the variant means “inherit from base”. A field with a value set means “use this value”. The variant only needs to specify fields it wants to override; all others come from the base surface.

Use sparse merge for variants that differ only in one or two aspects, for example a staging variant that overrides only the target endpoint.

#### Complete snapshot

Every overridable field is wholesale-replaced from the override, including fields set to no value (which clear the base value). Surface-level identifiers (Listener address, Channel Route, Protocol, and the outbound listen address) are still carried from the base; variants cannot change those.

Use complete snapshots when the variant was created as a full copy of the surface at a point in time and must not silently inherit later base edits.

## Access Point overrides

A subset of [Access Point](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/access-point.md) fields that a variant can override. The following fields cannot be overridden and are always inherited from the base:

- Listener address

- Channel Route

- Protocol

All other Access Point fields are overridable per variant.

## Related

- [Surface reference](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/surface-reference.md): Top-level surface fields including the Default Variant setting.

- [Surfaces concept model](/products/affinidi-trust-fabric/agent-gateway/concepts/surfaces.md#surface-variants): Conceptual explanation of variants and the audit trail model.