nomad/website/content/api-docs/task-api.mdx

---
layout: api
page_title: Task HTTP API
description: |-
  Jobs can access Nomad's HTTP API via the Task API.
---

# Task API

Nomad's Task API provides every task managed by Nomad with a Unix Domain Socket
(UDS) to access the local agent's HTTP API. Regardless of agent configuration
the Task API does *not* require [mTLS][], but *always* requires authentication.
See below for details.

The Unix Domain Socket is located at `${NOMAD_SECRETS_DIR}/api.sock`.

## Rationale

Nomad's HTTP API is available on every agent at the configured
[`bind_addr`][bind_addr]. While this is convenient for user access, it is not
always accessible to workloads running on Nomad. These workloads may have a
network configuration that makes it impossible to access the agent HTTP
address, or the agent's HTTP address may be difficult for workloads to discover
in a way that's portable between Nomad nodes and clusters.

A Unix Domain Socket is a way to expose network services that works with most
runtimes and operating systems and adds minimal complexity or runtime overhead
to Nomad.

## Security

Unlike the agent's HTTP API, the Task API *always requires authentication* even
if [ACLs][acl] are disabled.  This allows Nomad to always make the Task API
available even if the workload is untrusted. If ACLs are enabled, the [anonymous
policy][anon] is not available via the Task API.

Both [ACL Tokens][acl-tokens] and [Workload Identities][workload-id] are
accepted. Once the Task API has authenticated the credentials, the normal
endpoint-specific authorization is applied when ACLs are enabled.

The Workload Identity should be used by tasks accessing the Task API.

An ACL Token should be used when an operator is accessing the Task API via
[`nomad alloc exec`][alloc-exec] or when a task is proxying Nomad HTTP requests
on behalf of an authenticated user. The Task API could be used by a proxy
presenting Nomad's UI with a standard TLS certificate for browsers.

If [`task.user`][task-user] is set in the jobspec, the Task API will only be
usable by that user. Otherwise the Unix Domain Socket is accessible by any
user.

mTLS is never enabled for the Task API since traffic never leaves the node.

## Using the Task API

The following jobspec will use the Task API to set [Dynamic Node Metadata][dnm]
and exit.

```hcl
job "taskapi-example" {
  type = "batch"

  group "taskapi-example" {

    task "taskapi" {
      driver = "docker"

      config {
        image = "curlimages/curl:7.87.0"
        args = [
          "--unix-socket", "${NOMAD_SECRETS_DIR}/api.sock",
          "-H", "Authorization: Bearer ${NOMAD_TOKEN}",
          "--data-binary", "{\"Meta\": {\"example\": \"Hello World!\"}}",
          "--fail-with-body",
          "--verbose",
          "localhost/v1/client/metadata",
        ]
      }

      identity {
        env = true
      }
    }
  }
}
```

If the job was able to run successfully after about 10 seconds you can observe
the outcome by searching for the updated Node's metadata:

```shell-session
$ nomad node status -filter 'Meta.example == "Hello World!"'
```

## Limitations

- Using the Task API Unix Domain Socket on Windows [requires][windows] Windows
build 17063 or later.

[acl]: /nomad/docs/secure/acl/
[acl-tokens]: /nomad/docs/secure/acl/#tokens
[alloc-exec]: /nomad/commands/alloc/exec
[anon]: /nomad/docs/secure/acl#policies
[bind_addr]: /nomad/docs/configuration
[mTLS]: /nomad/docs/secure/traffic/tls
[task-user]: /nomad/docs/job-specification/task#user
[workload-id]: /nomad/docs/concepts/workload-identity
[windows]: https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/
[dnm]: /nomad/api-docs/client#update-dynamic-node-metadata