> This page is for Workload Identity, version Latest · v1.16.0-rc.7 (default).
> For other versions, use one of these documentation indexes:
> - Latest · v1.16.0-rc.7 (default): https://docs.nvidia.com/workload-identity/v1.16.0-rc.7/llms.txt
> - v1.16.0-rc.5: https://docs.nvidia.com/workload-identity/v1.16.0-rc.5/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/workload-identity/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/workload-identity/_mcp/server.

# Token-fetcher user guide

The injected `dsx-token-fetcher` sidecar exchanges the workload's local [SPIRE](https://spiffe.io/docs/latest/spire-about/)
JWT-SVID for a DSX JWT-SVID and refreshes the token file before expiry. NVIDIA
Workload Identity must have Pod token fetching enabled.

## Kubernetes Pods

Add the service label and token-fetcher annotations to the Pod template:

```yaml
spec:
  template:
    metadata:
      labels:
        spiffe.nvidia.com/service: dsx
      annotations:
        spiffe.nvidia.com/inject-dsx-token-fetcher: "true"
        spiffe.nvidia.com/token-audience: spiffe://ds9.dsx.nvid.id/openbao
```

Use the relying party's audience. For a Pod, put the labels and annotations
directly under `metadata`.

Application containers receive the token through a read-only mount:

```text
/run/secrets/nvidia.com/dsx/token
```

Apply [`non-dpf-pod.yaml`](https://github.com/dsx-ai-factory/nvidia-workload-identity/blob/v1.16.0-rc.7/examples/token-fetcher/non-dpf-pod.yaml) and wait for the example token
reader to become ready:

```bash
kubectl apply -f examples/token-fetcher/non-dpf-pod.yaml
kubectl wait --for=condition=Ready pod/dsx-token-fetcher-example --timeout=2m
kubectl exec dsx-token-fetcher-example -- \
  test -s /run/secrets/nvidia.com/dsx/token
```

## DPUService Pods

Configure the external [DPF identity templates](/workload-identity/charts/dsx-identity#dpf-identity-configuration)
and opt the DPUService into SPIFFE registration. The example packages a
token-fetcher-enabled DaemonSet in the
[`dsx-token-fetcher-example`](/workload-identity/charts/dsx-token-fetcher-example) chart:

```yaml
spec:
  security:
    spiffe: {}
  helmChart:
    values:
      audience: spiffe://ds9.dsx.nvid.id/openbao
```

Set the audience and pin the chart version for persistent environments, then
apply [`dpu-service.yaml`](https://github.com/dsx-ai-factory/nvidia-workload-identity/blob/v1.16.0-rc.7/examples/token-fetcher/dpu-service.yaml):

```bash
kubectl apply -f examples/token-fetcher/dpu-service.yaml
```

## Consume the token file

Cache the token and watch `/run/secrets/nvidia.com/dsx`, not the token file
inode. Refresh replaces the file atomically. Reread on directory changes and on
a polling interval in case a change event is lost:

```text
path = "/run/secrets/nvidia.com/dsx/token"
token = read(path)

loop:
  wait for a parent-directory change or polling timeout
  if next = read(path):
    atomically replace cached token with next
  else:
    clear cached token
```

The fetcher preserves an unexpired token after a failed refresh and removes it
after expiry. Treat an empty cache as an authentication failure. See [Consume a
DSX JWT-SVID](/workload-identity/user-guide/examples#consume-a-dsx-jwt-svid) to use the token.