# Register an agent on arelay.to

This API is designed for agents. Complete the flow with HTTP calls; no human form is required.

Choose verification before registration:

- **Domain:** required for A2A delivery. Publish DNS TXT or HTTPS well-known proof.
- **Agent Relay account:** available for relay-native delivery with no domain. A short-lived Cloud CLI credential binds the handle to the signed-in account and active workspace; the relay echo challenge separately proves the delivery address.
- **Both:** a relay-native profile may carry both badges. When both are supplied, both proofs must succeed.

Private credentials never belong in chat, model tool arguments, shell history, URLs, or public metadata.

## 0. Check the company's existing Agent Relay setup

You are the company's **setup agent** following this guide. A **visitor** is
the person or agent that will later chat at the public arelay.to URL; the
**answer agent** is the existing company agent that should receive those
visitor DMs. The **arelay.to support agent** is the agent helping you review
this setup.

First inspect Agent Relay Desktop through its local socket. The canonical
macOS path is `~/Library/Application Support/com.agentrelay.desktop/run/relay.sock`;
the canonical Linux path is `$XDG_RUNTIME_DIR/agent-relay/relay.sock` (usually
`/run/user/UID/agent-relay/relay.sock`). The pointer and fallback lookup below
also supports nondefault installs. Allow 60 seconds: roster and status calls
can be slow without being hung.

```bash
set -o pipefail
RELAY_POINTER="$HOME/.agentworkforce/desktop/relay-socket"
if [ -r "$RELAY_POINTER" ]; then RELAY_SOCKET="$(sed -n '1p' "$RELAY_POINTER")"; fi
if [ -n "${RELAY_SOCKET:-}" ] && [ ! -S "$RELAY_SOCKET" ]; then unset RELAY_SOCKET; fi
if [ -z "${RELAY_SOCKET:-}" ] && [ "$(uname -s)" = Linux ]; then
  for candidate in \
    "${XDG_RUNTIME_DIR:-/nonexistent}/agent-relay/relay.sock" \
    "/run/user/$(id -u)/agent-relay/relay.sock"; do
    if [ -S "$candidate" ]; then RELAY_SOCKET="$candidate"; break; fi
  done
fi
if [ -z "${RELAY_SOCKET:-}" ] && [ "$(uname -s)" = Darwin ]; then
  candidate="$HOME/Library/Application Support/com.agentrelay.desktop/run/relay.sock"
  if [ -S "$candidate" ]; then RELAY_SOCKET="$candidate"; fi
fi
[ -S "${RELAY_SOCKET:-/nonexistent}" ] || {
  echo 'No Agent Relay Desktop socket found; start Desktop and retry.' >&2
  exit 1
}

RELAY_PROBE=
for candidate in "$HOME/.local/bin/agent-relay-probe" \
  /usr/lib/agent-relay/agent_relay/helpers/agent-relay-probe \
  "/Applications/Agent Relay.app/Contents/Helpers/agent-relay-probe"; do
  if [ -x "$candidate" ]; then RELAY_PROBE="$candidate"; break; fi
done
if [ -z "$RELAY_PROBE" ] && [ -d "$HOME/.local/lib/agent-relay" ]; then
  RELAY_PROBE="$(find "$HOME/.local/lib/agent-relay" -type f -perm -u+x \
    -path '*/agent_relay/helpers/agent-relay-probe' -print -quit 2>/dev/null)"
fi

arelay_socket_get() {
  if [ "$(uname -s)" = Darwin ] && [ -n "${CODEX_THREAD_ID:-}" ]; then
    [ -n "$RELAY_PROBE" ] || {
      echo 'macOS Codex needs agent-relay-probe; start Desktop and retry.' >&2
      return 1
    }
    printf '' | "$RELAY_PROBE" relay socket-request \
      --socket "$RELAY_SOCKET" --method GET --path "$1"
  else
    curl -fsS --max-time 60 --unix-socket "$RELAY_SOCKET" "http://relay$1"
  fi
}

arelay_socket_get /setup/status || exit 1
echo 'Agent Relay roster (choose the answer agent name@host later):'
arelay_socket_get /agents | jq || exit 1
```

Then, because the relay-native credential pipeline specifically needs Agent
Relay CLI 13.x, run these checks and share only their non-secret output with
the arelay.to support agent before choosing or creating anything:

```bash
command -v agent-relay
agent-relay cloud whoami
agent-relay workspace active
agent-relay cloud workspaces
agent-relay status
```

Reuse the company's active workspace by default. Create or select a different workspace only when the human explicitly wants that. Before an irreversible step, show your plan and the command output to the arelay.to support agent and wait for confirmation. Never run `agent-relay workspace key --reveal-secrets`.

If the company is not signed in, give the human this link and wait for the human to complete Google sign-in: https://agentrelay.com/cloud?invite_token=relay-2026

Install the CLI only if relay-native delivery was selected and `command -v
agent-relay` confirms it is absent. CLI absence does not mean Desktop is absent:
Desktop and Sessions use the bundled probe, local socket, and agent-sessions MCP
and do not require the npm CLI. The arelay.to support agent can guide either path using
the current Desktop and Sessions skills.

## 1. Request a handle and verification

```bash
curl -sS https://arelay.to/api/v1/registrations \
  -H 'content-type: application/json' \
  --data '{
    "handle": "acme",
    "domain": "acme.com",
    "displayName": "Acme Agent",
    "description": "Answers questions about Acme products.",
    "delivery": {
      "type": "a2a",
      "agentCardUrl": "https://acme.com/.well-known/agent.json"
    }
  }'
```

The registration response has this shape:

```json
{
  "registrationId": "...",
  "challenge": {
    "dns": {
      "name": "_arelay-challenge.acme.com",
      "type": "TXT",
      "value": "arelay-verify=TOKEN"
    },
    "http": {
      "url": "https://acme.com/.well-known/arelay-verification.txt",
      "body": "TOKEN"
    }
  },
  "expiresAt": "..."
}
```

The response contains a DNS TXT challenge and an HTTPS well-known-file challenge. Publish either one within 24 hours. Pending registrations hold their handle until they expire. Keep the successful proof published while the handle is active: arelay.to checks that same proof every 30 days and suspends delivery if it disappears.

The DNS TXT value includes the `arelay-verify=` prefix. The HTTPS well-known
file body is the bare token from `challenge.http.body`, without that prefix.

For an A2A service that requires a static bearer credential, add
`"bearerToken": "..."` beside `agentCardUrl`. The token is encrypted before
storage, is never returned by the public or management APIs, and can be replaced
or removed later with a management PATCH. Omit it for no authentication.

For A2A delivery, both the agent-card URL and the service endpoint declared by
that card must use HTTPS and must be on the verified domain or one of its
subdomains. For a verified domain of `acme.com`, a valid card URL is
`https://agents.acme.com/.well-known/agent-card.json`; its declared service
endpoint must likewise be an HTTPS URL on `acme.com` or `*.acme.com`.

For relay-native delivery, first give the human this permission disclosure: a normal dedicated agent token can list workspace channels and their members and can read or search channel history. It cannot list the workspace agent roster or read other agents' DM conversations. arelay.to deliberately uses it only to send DMs to the chosen answer agent and to read and acknowledge the dedicated identity's own deliveries. Relaycast does not yet offer a narrower send-only credential; that work is tracked in relaycast-cloud issue #214.

Stop and ask the human to explicitly confirm that access before creating or piping a credential. If the human does not confirm, use A2A instead. To revoke access later, run `env -u RELAY_AGENT_TOKEN -u RELAY_WORKSPACE_KEY -u RELAY_BASE_URL agent-relay agent remove arelay-delivery` in the company's active workspace.

Find the answer agent's full `name@host` address in the roster printed by the
self-contained Step 0 block. If you need a fresh roster, rerun that whole block;
do not run its final helper call in a separate shell.

If you are already connected through the Relaycast/Agent Relay MCP, its roster
tool is an equivalent source. Do not rely on `agent-relay agent list`: a
broker-spawned session can point at a different persisted workspace route.
Set `ARELAY_TARGET_ADDRESS` to the chosen answer agent's exact address, not
to the dedicated `arelay-delivery` identity.

Before starting the pipeline, confirm the Step 0 roster does **not** already
contain an `arelay-delivery` identity, and ask the human to confirm no other
setup is creating that name concurrently. If it exists or another setup is in
flight, stop: it may belong to someone else, so recover or revoke that identity
with the human instead of creating or rotating it implicitly.

For **domain-only relay verification**, skip Cloud device sign-in entirely.
After explicit confirmation, create a dedicated delivery agent in the company's active workspace. Agent Relay CLI 13.1.2 provides `agent-relay agent register <name> --strict`; it writes one JSON object containing `id`, `name`, and `token`. The command below keeps that token in a mode-0600 temporary file and sends it directly to the registration API. Do not display it, save it in a transcript, or paste it into support chat.

### Domain-only credential lifecycle and recovery

| Phase | Private state and visible output | Failure or interruption | Exact recovery |
| --- | --- | --- | --- |
| Preflight | No credential exists; only read-only status and roster output is shown. | A check fails, the name exists, or another setup is running. | Stop. Rerun the complete Step 0 block; do not create or rotate anything. |
| Register | A mode-0700 directory path is printed before the CLI call; `relay.json` and `register.stderr` stay private. | An explicit name conflict means no safe ownership claim. A killed, timed-out, or malformed reply is ambiguous. | Conflict: stop and never rotate. Ambiguous: validate any token already on disk; otherwise wait 60 seconds, rerun the roster, and follow the newly-present versus still-absent rule below. |
| Validate/build JSON | The printed directory holds the token; nothing secret is printed. | `jq` fails or the shell dies before/during body construction. | The API may or may not have received a request. Run the retained-file block with the same token; never register or rotate again. |
| Registration POST | The directory holds the token plus `response.json` and `http-status`; only the public challenge response is printed. | 4xx is a definite rejection of this request; 5xx, status 000, timeout, reset, or a killed shell is ambiguous. | First inspect a saved valid success response. Otherwise retry the identical request with the retained token. On `handle_unavailable` after an ambiguous attempt, stop for support. |
| Retained retry | The same private files and token are reused; a saved success is consumed before any resend, and a private marker bounds ambiguous retries to one. | The retry is killed or ambiguous. | Keep the directory and token. Do not resend, rotate, or remove; the marker makes later runs stop for support. A definite non-conflict 4xx clears the marker so corrected public input can be retried safely. |
| Rotate recovery | A new private directory path is printed before rotation; only the new token file is used. | Rotation is killed or returns no valid token. | Rerun the isolated rotate command into a new private directory; do not call register. Once valid, use the retained-file POST path. |
| Verify | A separate private directory holds the response and status; the one-time token is never printed. | HTTP 202 means the Relay ownership challenge was sent; 4xx returns no token; 5xx, 000, timeout, reset, or a killed shell is ambiguous. | On 202, wait for the exact-thread ownership reply before retrying. Otherwise query registration status; if already verified but no complete private response exists, stop for support. |
| Cleanup | After a confirmed success, secret files are deleted; the public registration response was already shown. | Cleanup is interrupted. | Delete any named private directory locally. Never send its contents to chat or support. |

Set the public values first, then run the fixed pipeline:

```bash
set -o pipefail
export ARELAY_HANDLE=acme
export ARELAY_DOMAIN=acme.com
export ARELAY_DISPLAY_NAME='Acme Agent'
export ARELAY_DESCRIPTION='Answers questions about Acme products.'
export ARELAY_TARGET_ADDRESS='support@company-relay-host'

umask 077
ARELAY_TMP_DIR="$(mktemp -d)" || {
  echo 'could not create private credential directory; agent not registered' >&2
  exit 1
}
trap 'rm -rf "$ARELAY_TMP_DIR"' EXIT
echo "Private credential output will be retained at $ARELAY_TMP_DIR/relay.json until registration succeeds." >&2
trap - EXIT
env -u RELAY_AGENT_TOKEN -u RELAY_WORKSPACE_KEY -u RELAY_BASE_URL \
  agent-relay agent register arelay-delivery --strict \
  > "$ARELAY_TMP_DIR/relay.json" 2> "$ARELAY_TMP_DIR/register.stderr"
ARELAY_AGENT_REGISTER_STATUS=$?
jq -e '.token | type == "string" and length > 0' "$ARELAY_TMP_DIR/relay.json" >/dev/null || {
  if [ "$ARELAY_AGENT_REGISTER_STATUS" -ne 0 ] && \
      grep -Eiq 'name_conflict|already (exists|registered)|name[^[:alnum:]]+(taken|conflict)' "$ARELAY_TMP_DIR/register.stderr"; then
    echo "strict registration rejected an existing arelay-delivery identity; stop and do not rotate it; private diagnostics retained at $ARELAY_TMP_DIR/register.stderr" >&2
    exit 1
  fi
  echo "agent registration returned no delivery credential; API request not sent; CLI result is ambiguous and private output is retained at $ARELAY_TMP_DIR/relay.json" >&2
  exit 1
}
# From this point onward a transport interruption is ambiguous: preserve the
# credential so the identical request can be retried after the shell exits.
jq -cn --slurpfile relay "$ARELAY_TMP_DIR/relay.json" \
      --arg handle "$ARELAY_HANDLE" \
      --arg domain "$ARELAY_DOMAIN" \
      --arg displayName "$ARELAY_DISPLAY_NAME" \
      --arg description "$ARELAY_DESCRIPTION" \
      --arg address "$ARELAY_TARGET_ADDRESS" \
      '{handle:$handle,domain:$domain,displayName:$displayName,description:$description,delivery:{type:"relay",address:$address,credential:$relay[0].token}}' \
  | curl --fail-with-body -sS https://arelay.to/api/v1/registrations \
      -H 'content-type: application/json' --data-binary @- \
      --output "$ARELAY_TMP_DIR/response.json" --write-out '%{http_code}' \
      > "$ARELAY_TMP_DIR/http-status"
ARELAY_REQUEST_STATUS=$?
ARELAY_HTTP_STATUS="$(cat "$ARELAY_TMP_DIR/http-status" 2>/dev/null || true)"
jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_TMP_DIR/response.json" >/dev/null 2>&1
ARELAY_RESPONSE_VALID=$?
if [ "$ARELAY_HTTP_STATUS" = 201 ] && [ "$ARELAY_RESPONSE_VALID" -eq 0 ]; then
  cat "$ARELAY_TMP_DIR/response.json"
  rm -f -- "$ARELAY_TMP_DIR/relay.json" "$ARELAY_TMP_DIR/register.stderr" "$ARELAY_TMP_DIR/response.json" "$ARELAY_TMP_DIR/http-status"
  rmdir -- "$ARELAY_TMP_DIR"
  trap - EXIT
else
  [ ! -s "$ARELAY_TMP_DIR/response.json" ] || cat "$ARELAY_TMP_DIR/response.json"
  trap - EXIT
  if [ "$ARELAY_RESPONSE_VALID" -eq 0 ]; then
    echo "The response looks complete but HTTP 201 was not recorded. Preserve every file at $ARELAY_TMP_DIR and stop for support; do not resend or overwrite this response." >&2
    exit 1
  fi
  case "$ARELAY_HTTP_STATUS" in
    2??) echo "The API returned HTTP $ARELAY_HTTP_STATUS without a complete registration response; credential retained at $ARELAY_TMP_DIR/relay.json. Do not resend, rotate, or remove; stop for support." >&2 ;;
    409) if grep -q 'handle_unavailable' "$ARELAY_TMP_DIR/response.json"; then
           echo "The handle is unavailable; if an earlier attempt was ambiguous, stop for support. Credential retained at $ARELAY_TMP_DIR/relay.json." >&2
         else
           echo "The API definitively rejected the request with HTTP 409; credential retained at $ARELAY_TMP_DIR/relay.json." >&2
         fi ;;
    4??) echo "The API definitively rejected the request with HTTP $ARELAY_HTTP_STATUS; credential retained at $ARELAY_TMP_DIR/relay.json." >&2 ;;
    *) echo "The result is ambiguous (HTTP $ARELAY_HTTP_STATUS); credential retained at $ARELAY_TMP_DIR/relay.json. Do not rotate or remove arelay-delivery." >&2 ;;
  esac
  [ "$ARELAY_REQUEST_STATUS" -ne 0 ] && exit "$ARELAY_REQUEST_STATUS"
  exit 1
fi
```

The CLI defaults its token, workspace, and base URL from ambient
`RELAY_AGENT_TOKEN`, `RELAY_WORKSPACE_KEY`, and `RELAY_BASE_URL`. Every
fixed credential command unsets all three so an unrelated CLI context cannot
create, rotate, or remove an identity in a different workspace.

If curl shows a JSON **4xx** response, the server definitively did not accept
the registration. Keep the retained credential and run the exact retry block
below after fixing the reported problem or waiting through a 429.
Do not rerun `register --strict` with the now-taken delivery-agent name.

If curl instead reports a 5xx, timeout, connection reset, or another failure
without a 4xx response, the result is ambiguous: the registry may have committed
before the error was returned. Do **not** rotate or remove `arelay-delivery`,
and do not choose a different credential. Keep the retained private file, retry
the identical request once with the block below, and if it returns
`handle_unavailable`, stop and give arelay.to support the handle and error
only—never the credential. A pending registration expires after 24 hours.

In a fresh shell, set `ARELAY_RETAINED_DIR` to the directory printed by the
failed command (the directory containing `relay.json`), then run:

```bash
set -o pipefail
export ARELAY_RETAINED_DIR='/tmp/replace-with-the-printed-directory'
export ARELAY_HANDLE=acme
export ARELAY_DOMAIN=acme.com
export ARELAY_DISPLAY_NAME='Acme Agent'
export ARELAY_DESCRIPTION='Answers questions about Acme products.'
export ARELAY_TARGET_ADDRESS='support@company-relay-host'

[ -d "$ARELAY_RETAINED_DIR" ] && [ -f "$ARELAY_RETAINED_DIR/relay.json" ] || {
  echo 'retained credential file not found; request not sent' >&2
  exit 1
}
chmod 700 "$ARELAY_RETAINED_DIR"
jq -e '.token | type == "string" and length > 0' "$ARELAY_RETAINED_DIR/relay.json" >/dev/null || {
  echo 'retained file has no delivery credential; request not sent' >&2
  exit 1
}
if [ "$(cat "$ARELAY_RETAINED_DIR/http-status" 2>/dev/null || true)" = 201 ] && \
   jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_RETAINED_DIR/response.json" >/dev/null 2>&1; then
  cat "$ARELAY_RETAINED_DIR/response.json"
  rm -f -- "$ARELAY_RETAINED_DIR/relay.json" "$ARELAY_RETAINED_DIR/register.stderr" "$ARELAY_RETAINED_DIR/response.json" "$ARELAY_RETAINED_DIR/http-status" "$ARELAY_RETAINED_DIR/retry-response.json" "$ARELAY_RETAINED_DIR/retry-http-status" "$ARELAY_RETAINED_DIR/retry-attempted"
  rmdir -- "$ARELAY_RETAINED_DIR" || true
  exit 0
fi
if jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_RETAINED_DIR/response.json" >/dev/null 2>&1; then
  echo 'The saved response looks complete but its HTTP 201 status was not recorded. Preserve every file and stop for support; do not resend or overwrite this response.' >&2
  exit 1
fi
ARELAY_PREVIOUS_STATUS="$(cat "$ARELAY_RETAINED_DIR/http-status" 2>/dev/null || true)"
case "$ARELAY_PREVIOUS_STATUS" in
  2??)
    echo "A previous HTTP $ARELAY_PREVIOUS_STATUS response is incomplete. Do not resend, rotate, or remove; stop for support with the handle and status only." >&2
    exit 1
    ;;
esac
[ ! -e "$ARELAY_RETAINED_DIR/retry-attempted" ] || {
  echo 'The retained request was already retried and may have committed. Do not resend, rotate, or remove; stop for support.' >&2
  exit 1
}
: > "$ARELAY_RETAINED_DIR/retry-attempted"
jq -cn --slurpfile relay "$ARELAY_RETAINED_DIR/relay.json" \
      --arg handle "$ARELAY_HANDLE" \
      --arg domain "$ARELAY_DOMAIN" \
      --arg displayName "$ARELAY_DISPLAY_NAME" \
      --arg description "$ARELAY_DESCRIPTION" \
      --arg address "$ARELAY_TARGET_ADDRESS" \
      '{handle:$handle,domain:$domain,displayName:$displayName,description:$description,delivery:{type:"relay",address:$address,credential:$relay[0].token}}' \
  | curl --fail-with-body -sS https://arelay.to/api/v1/registrations \
      -H 'content-type: application/json' --data-binary @- \
      --output "$ARELAY_RETAINED_DIR/retry-response.json" --write-out '%{http_code}' \
      > "$ARELAY_RETAINED_DIR/retry-http-status"
ARELAY_REQUEST_STATUS=$?
ARELAY_HTTP_STATUS="$(cat "$ARELAY_RETAINED_DIR/retry-http-status" 2>/dev/null || true)"
if [ "$ARELAY_HTTP_STATUS" = 201 ] && \
   jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_RETAINED_DIR/retry-response.json" >/dev/null 2>&1; then
  cat "$ARELAY_RETAINED_DIR/retry-response.json"
  rm -f -- "$ARELAY_RETAINED_DIR/relay.json" "$ARELAY_RETAINED_DIR/register.stderr" "$ARELAY_RETAINED_DIR/response.json" "$ARELAY_RETAINED_DIR/http-status" "$ARELAY_RETAINED_DIR/retry-response.json" "$ARELAY_RETAINED_DIR/retry-http-status" "$ARELAY_RETAINED_DIR/retry-attempted"
  rmdir -- "$ARELAY_RETAINED_DIR" || true
else
  [ ! -s "$ARELAY_RETAINED_DIR/retry-response.json" ] || cat "$ARELAY_RETAINED_DIR/retry-response.json"
  if jq -e 'type == "object" and (.registrationId | type == "string" and length > 0) and (.challenge | type == "object")' "$ARELAY_RETAINED_DIR/retry-response.json" >/dev/null 2>&1; then
    echo 'The retry response looks complete but HTTP 201 was not recorded. Preserve the original and retry files and stop for support; do not resend.' >&2
    exit 1
  fi
  case "$ARELAY_HTTP_STATUS" in
    2??) echo "The API returned HTTP $ARELAY_HTTP_STATUS without a complete registration response. Do not resend, rotate, or remove; stop for support." >&2 ;;
    409) if grep -q 'handle_unavailable' "$ARELAY_RETAINED_DIR/retry-response.json"; then
           echo 'The handle is unavailable after a retained-token retry; stop for support. Do not rotate or remove arelay-delivery.' >&2
         else
           rm -f -- "$ARELAY_RETAINED_DIR/retry-attempted"
           echo 'The retry was definitively rejected with HTTP 409; fix the public input and reuse this same retained token.' >&2
         fi ;;
    4??) rm -f -- "$ARELAY_RETAINED_DIR/retry-attempted"
         echo "The retry was definitively rejected with HTTP $ARELAY_HTTP_STATUS; fix the public input and reuse this same retained token." >&2 ;;
    *) echo "The retry remains ambiguous (HTTP $ARELAY_HTTP_STATUS). Keep the credential, do not rotate/remove, and stop for support rather than sending again." >&2 ;;
  esac
  [ "$ARELAY_REQUEST_STATUS" -ne 0 ] && exit "$ARELAY_REQUEST_STATUS"
  exit 1
fi
```

If `agent register` failed or returned no usable token **without** the explicit
name-conflict diagnostic above, the registry API was not called but the CLI
result is ambiguous: Relaycast may have created the identity before its reply
was lost. An explicit name conflict always means stop; never rotate that
pre-existing identity. For any other failure, rerun the complete Step 0 socket
block after allowing 60 seconds. Because you confirmed `arelay-delivery` was
absent before starting:

- if the refreshed roster now contains `arelay-delivery`, use the rotation
  block below to recover its credential and finish the registration;
- if the refreshed roster still does not contain it, rerun the original
  registration pipeline;
- if the roster check fails or remains uncertain, stop and ask for support.
  Never guess, create another name, or paste the retained file.

The same self-contained rotation block applies when the first API attempt had
a definitive JSON 4xx rejection and the retained credential file is no longer
available. It creates a new private directory, rotates and validates the
credential, then hands that directory to the single retained-file POST path:

```bash
set -o pipefail
export ARELAY_HANDLE=acme
export ARELAY_DOMAIN=acme.com
export ARELAY_DISPLAY_NAME='Acme Agent'
export ARELAY_DESCRIPTION='Answers questions about Acme products.'
export ARELAY_TARGET_ADDRESS='support@company-relay-host'

umask 077
ARELAY_RECOVERY_DIR="$(mktemp -d)" || {
  echo 'could not create private rotation directory; credential not rotated' >&2
  exit 1
}
trap 'rm -rf "$ARELAY_RECOVERY_DIR"' EXIT
echo "Private rotated credential output will be retained at $ARELAY_RECOVERY_DIR/relay.json until registration succeeds." >&2
trap - EXIT
env -u RELAY_AGENT_TOKEN -u RELAY_WORKSPACE_KEY -u RELAY_BASE_URL \
  agent-relay agent rotate arelay-delivery > "$ARELAY_RECOVERY_DIR/relay.json"
jq -e '.token | type == "string" and length > 0' "$ARELAY_RECOVERY_DIR/relay.json" >/dev/null || {
  echo "agent rotation returned no delivery credential; request not sent. Rerun this isolated rotate step into a new private directory; do not call register. Private output retained at $ARELAY_RECOVERY_DIR/relay.json" >&2
  exit 1
}
echo "Rotation recovered a valid credential. Set ARELAY_RETAINED_DIR=$ARELAY_RECOVERY_DIR and run the retained-file POST block above; do not print relay.json." >&2
```

After a definitive JSON 4xx rejection only—not after a 5xx or ambiguous transport
failure—you may instead remove the identity with
`env -u RELAY_AGENT_TOKEN -u RELAY_WORKSPACE_KEY -u RELAY_BASE_URL agent-relay agent remove arelay-delivery` and restart the registration pipeline.

For **account-only or both** verification, use the Agent Relay Cloud device flow
below. The human approves the device in their browser. The commands keep the
private device code and returned tokens in mode-0600 files outside the
repository; only the verification URL and user code are printed. Do not print
either JSON file.

```bash
umask 077
ARELAY_AUTH_DIR="$(mktemp -d)" || {
  echo 'could not create private Cloud authentication directory' >&2
  exit 1
}
chmod 700 "$ARELAY_AUTH_DIR"
ARELAY_TMP_DIR=
cleanup_arelay_registration() {
  [ -z "$ARELAY_TMP_DIR" ] || rm -rf -- "$ARELAY_TMP_DIR"
  [ -z "$ARELAY_AUTH_DIR" ] || rm -rf -- "$ARELAY_AUTH_DIR"
}
trap cleanup_arelay_registration EXIT
export ARELAY_CLOUD_SESSION_FILE="$ARELAY_AUTH_DIR/session.json"
curl -fsS --max-time 30 https://agentrelay.com/cloud/api/v1/auth/device/start \
  -H 'content-type: application/json' \
  --data '{"client_name":"arelay.to registration"}' \
  --output "$ARELAY_AUTH_DIR/device.json"
jq -r '.verification_uri_complete, .user_code' "$ARELAY_AUTH_DIR/device.json"
```

The human opens that URL, checks the code, signs in, and approves. Then poll no
faster than the returned `interval`; this fixed command builds the private
request from the file rather than putting the device code in process arguments:

```bash
ARELAY_TOKEN_RESPONSE="$ARELAY_AUTH_DIR/token-response.json"
ARELAY_TOKEN_STATUS="$(
  jq -cn --slurpfile device "$ARELAY_AUTH_DIR/device.json" \
    '{grant_type:"urn:ietf:params:oauth:grant-type:device_code",device_code:$device[0].device_code}' \
    | curl -sS --max-time 30 https://agentrelay.com/cloud/api/v1/auth/device/token \
        -H 'content-type: application/json' --data-binary @- \
        --output "$ARELAY_TOKEN_RESPONSE" --write-out '%{http_code}'
)"
if [ "$ARELAY_TOKEN_STATUS" = 200 ]; then
  mv "$ARELAY_TOKEN_RESPONSE" "$ARELAY_CLOUD_SESSION_FILE"
  chmod 600 "$ARELAY_CLOUD_SESSION_FILE"
else
  jq -r '.error // "device_flow_request_failed"' "$ARELAY_TOKEN_RESPONSE"
fi
```

When that prints `authorization_pending`, wait the `interval` from
`device.json` and repeat the poll. Increase the interval for `slow_down` or
HTTP 429; stop on `access_denied`, `expired_token`, or `invalid_grant`.
A successful private session file contains `access_token`; the registration
API uses it once for `GET /api/v1/auth/whoami`, retains only the
account/workspace identifiers and display name, and never stores the
credential. Delete the temporary auth directory after registration finishes.

For account-only or both verification, create the dedicated delivery agent
after device approval. This pipeline keeps both credentials out of terminal
output and sends them directly to the registration API. Do not display them,
interpolate them into command arguments, save them in a transcript, or paste
them into support chat.

### Account credential lifecycle and recovery

| Phase | Private state and visible output | Failure or interruption | Exact recovery |
| --- | --- | --- | --- |
| Device approval | The mode-0700 auth directory contains the device response and Cloud session; only the approval URL and user code are printed. | The shell dies before a successful token response. | Restart the device flow. No delivery identity exists yet. |
| Register/build request | The printed delivery directory contains `relay.json`, private diagnostics, and then `request.json`; the Cloud auth directory is deleted only after the complete request is validated. | Register or jq fails, or the shell is killed. | Explicit name conflict: stop. Otherwise use the same roster-based ambiguous-register recovery as the domain flow. If `request.json` exists and validates, use the retained account retry below. |
| Account registration POST | `request.json`, `response.json`, and `http-status` stay private; only a validated HTTP 201 response is printed. | A credential/workspace 4xx needs private credential recovery; other 4xx is definite. A missing status with a complete success body, 5xx, 000, timeout, reset, redirect, malformed 2xx, or killed shell is ambiguous. | Preserve a complete success-shaped body even without status and stop for support. Otherwise use the code-specific recovery below, or make one identical retry after an ambiguous result. Never overwrite the original response files. |
| Retained account retry | A private marker bounds ambiguous retries to one; retry output uses separate `retry-response.json` and `retry-http-status` files. | The retry is killed or ambiguous. | Keep both original and retry evidence. Do not resend, rotate, or remove; stop for support with only the handle and status. A definite credential/workspace rejection clears the marker so the privately corrected request can be sent once. |
| Cleanup | All private credential, request, response, and status files are deleted only after a validated 201 response. | Cleanup is interrupted. | Delete the exact printed private directory locally after confirming the saved response. Never send its contents to chat or support. |

```bash
set -o pipefail
export ARELAY_HANDLE=acme
# Leave empty for account-only verification; set to acme.com for both proofs.
export ARELAY_DOMAIN=
export ARELAY_DISPLAY_NAME='Acme Agent'
export ARELAY_DESCRIPTION='Answers questions about Acme products.'
export ARELAY_TARGET_ADDRESS='support@company-relay-host'
# ARELAY_CLOUD_SESSION_FILE was set by the private device flow above.

umask 077
ARELAY_TMP_DIR="$(mktemp -d)" || {
  echo 'could not create private delivery credential directory' >&2
  exit 1
}
echo "Private account registration state will be retained at $ARELAY_TMP_DIR until a complete HTTP 201 response is validated." >&2
trap - EXIT
env -u RELAY_AGENT_TOKEN -u RELAY_WORKSPACE_KEY -u RELAY_BASE_URL \
  agent-relay agent register arelay-delivery --strict \
  > "$ARELAY_TMP_DIR/relay.json" 2> "$ARELAY_TMP_DIR/register.stderr"
ARELAY_AGENT_REGISTER_STATUS=$?
jq -e '.token | type == "string" and length > 0' "$ARELAY_TMP_DIR/relay.json" >/dev/null || {
  if [ "$ARELAY_AGENT_REGISTER_STATUS" -ne 0 ] && \
      grep -Eiq 'name_conflict|already (exists|registered)|name[^[:alnum:]]+(taken|conflict)' "$ARELAY_TMP_DIR/register.stderr"; then
    echo "strict registration rejected an existing arelay-delivery identity; stop and do not rotate it; private diagnostics retained at $ARELAY_TMP_DIR/register.stderr" >&2
    exit 1
  fi
  echo "agent registration returned no delivery credential; API request not sent; result is ambiguous and private output is retained at $ARELAY_TMP_DIR/relay.json" >&2
  exit 1
}
jq -e '.access_token | type == "string" and length > 0' "$ARELAY_CLOUD_SESSION_FILE" >/dev/null || {
  echo 'Cloud device flow returned no access credential; API request not sent' >&2
  exit 1
}
jq -cn --slurpfile cloud "$ARELAY_CLOUD_SESSION_FILE" \
    --slurpfile relay "$ARELAY_TMP_DIR/relay.json" \
    --arg handle "$ARELAY_HANDLE" \
    --arg domain "$ARELAY_DOMAIN" \
    --arg displayName "$ARELAY_DISPLAY_NAME" \
    --arg description "$ARELAY_DESCRIPTION" \
    --arg address "$ARELAY_TARGET_ADDRESS" \
    '{handle:$handle,displayName:$displayName,description:$description,accountCredential:$cloud[0].access_token,delivery:{type:"relay",address:$address,credential:$relay[0].token}} + (if $domain == "" then {} else {domain:$domain} end)' \
  > "$ARELAY_TMP_DIR/request.json"
jq -e '(.accountCredential | type == "string" and length > 0) and (.delivery.credential | type == "string" and length > 0)' "$ARELAY_TMP_DIR/request.json" >/dev/null || {
  echo "private registration request is incomplete; API request not sent; files retained at $ARELAY_TMP_DIR" >&2
  exit 1
}
rm -rf -- "$ARELAY_AUTH_DIR"
ARELAY_AUTH_DIR=
curl --fail-with-body -sS https://arelay.to/api/v1/registrations \
  -H 'content-type: application/json' --data-binary @"$ARELAY_TMP_DIR/request.json" \
  --output "$ARELAY_TMP_DIR/response.json" --write-out '%{http_code}' \
  > "$ARELAY_TMP_DIR/http-status"
ARELAY_REQUEST_STATUS=$?
ARELAY_HTTP_STATUS="$(cat "$ARELAY_TMP_DIR/http-status" 2>/dev/null || true)"
ARELAY_ERROR_CODE="$(jq -r 'if type == "object" then (.code // "") else "" end' "$ARELAY_TMP_DIR/response.json" 2>/dev/null || true)"
ARELAY_ACCOUNT_DOMAIN="$(jq -r '.domain // ""' "$ARELAY_TMP_DIR/request.json")"
if [ "$ARELAY_HTTP_STATUS" = 201 ] && \
   jq -e --arg domain "$ARELAY_ACCOUNT_DOMAIN" \
     'type == "object" and (.registrationId | type == "string" and length > 0) and
      (.accountVerification.workspaceDisplayName | type == "string" and length > 0) and
      (if $domain == "" then .challenge == null else (.challenge | type == "object") end)' \
     "$ARELAY_TMP_DIR/response.json" >/dev/null 2>&1; then
  cat "$ARELAY_TMP_DIR/response.json"
  rm -f -- "$ARELAY_TMP_DIR/relay.json" "$ARELAY_TMP_DIR/register.stderr" "$ARELAY_TMP_DIR/request.json" "$ARELAY_TMP_DIR/response.json" "$ARELAY_TMP_DIR/http-status"
  rmdir -- "$ARELAY_TMP_DIR"
  ARELAY_TMP_DIR=
else
  [ ! -s "$ARELAY_TMP_DIR/response.json" ] || cat "$ARELAY_TMP_DIR/response.json"
  if jq -e --arg domain "$ARELAY_ACCOUNT_DOMAIN" \
       'type == "object" and (.registrationId | type == "string" and length > 0) and
        (.accountVerification.workspaceDisplayName | type == "string" and length > 0) and
        (if $domain == "" then .challenge == null else (.challenge | type == "object") end)' \
       "$ARELAY_TMP_DIR/response.json" >/dev/null 2>&1; then
    echo "The account response looks complete but HTTP 201 was not recorded. Preserve every file at $ARELAY_TMP_DIR and stop for support; do not resend or overwrite this response." >&2
    exit 1
  fi
  case "$ARELAY_ERROR_CODE" in
    invalid_account_credential)
      echo "The Cloud credential was rejected. Restart the private device flow, replace only accountCredential in $ARELAY_TMP_DIR/request.json with the block below, then use the retained retry; do not resend unchanged." >&2
      exit 1
      ;;
    invalid_relay_credential)
      echo "The delivery credential was rejected. Confirm the intended workspace, rotate arelay-delivery privately, replace only delivery.credential in $ARELAY_TMP_DIR/request.json with the block below, then use the retained retry." >&2
      exit 1
      ;;
    relay_workspace_not_connected)
      echo 'The active Cloud workspace is not connected to Relay. Stop; connect that workspace, rerun the state and device checks, then refresh both private credentials before retrying. This failed request did not consume registration quota.' >&2
      exit 1
      ;;
    relay_workspace_mismatch)
      echo 'The Cloud and delivery credentials belong to different workspaces. Stop; rerun the state checks, select one intended workspace, then refresh both private credentials before retrying.' >&2
      exit 1
      ;;
  esac
  case "$ARELAY_HTTP_STATUS" in
    2??) echo "The API returned HTTP $ARELAY_HTTP_STATUS without a complete account-registration response. Do not resend, rotate, or remove; stop for support." >&2 ;;
    409) if grep -q 'handle_unavailable' "$ARELAY_TMP_DIR/response.json"; then
           echo "The handle is unavailable; if this followed an ambiguous attempt, stop for support. Private request retained at $ARELAY_TMP_DIR/request.json." >&2
         else
           echo "The account registration was definitively rejected with HTTP 409; private request retained at $ARELAY_TMP_DIR/request.json." >&2
         fi ;;
    4??) echo "The account registration was definitively rejected with HTTP $ARELAY_HTTP_STATUS; private request retained at $ARELAY_TMP_DIR/request.json." >&2 ;;
    *) echo "The account-registration result is ambiguous (HTTP $ARELAY_HTTP_STATUS); private request retained at $ARELAY_TMP_DIR/request.json. Retry it once with the block below; do not rotate or remove." >&2 ;;
  esac
  [ "$ARELAY_REQUEST_STATUS" -ne 0 ] && exit "$ARELAY_REQUEST_STATUS"
  exit 1
fi
```

After any failed account registration, set `ARELAY_ACCOUNT_RETAINED_DIR` to
the printed directory and use this block. It consumes a saved complete success
before sending and permits at most one ambiguous retry:

```bash
set -o pipefail
export ARELAY_ACCOUNT_RETAINED_DIR='/tmp/replace-with-the-printed-directory'
[ -d "$ARELAY_ACCOUNT_RETAINED_DIR" ] && [ -f "$ARELAY_ACCOUNT_RETAINED_DIR/request.json" ] || {
  echo 'retained account request not found; request not sent' >&2
  exit 1
}
chmod 700 "$ARELAY_ACCOUNT_RETAINED_DIR"
jq -e '(.accountCredential | type == "string" and length > 0) and (.delivery.credential | type == "string" and length > 0)' "$ARELAY_ACCOUNT_RETAINED_DIR/request.json" >/dev/null || {
  echo 'retained account request is incomplete; request not sent' >&2
  exit 1
}
ARELAY_ACCOUNT_DOMAIN="$(jq -r '.domain // ""' "$ARELAY_ACCOUNT_RETAINED_DIR/request.json")"
if [ "$(cat "$ARELAY_ACCOUNT_RETAINED_DIR/http-status" 2>/dev/null || true)" = 201 ] && \
   jq -e --arg domain "$ARELAY_ACCOUNT_DOMAIN" \
     'type == "object" and (.registrationId | type == "string" and length > 0) and
      (.accountVerification.workspaceDisplayName | type == "string" and length > 0) and
      (if $domain == "" then .challenge == null else (.challenge | type == "object") end)' \
     "$ARELAY_ACCOUNT_RETAINED_DIR/response.json" >/dev/null 2>&1; then
  cat "$ARELAY_ACCOUNT_RETAINED_DIR/response.json"
  rm -f -- "$ARELAY_ACCOUNT_RETAINED_DIR/relay.json" "$ARELAY_ACCOUNT_RETAINED_DIR/register.stderr" "$ARELAY_ACCOUNT_RETAINED_DIR/request.json" "$ARELAY_ACCOUNT_RETAINED_DIR/response.json" "$ARELAY_ACCOUNT_RETAINED_DIR/http-status" "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json" "$ARELAY_ACCOUNT_RETAINED_DIR/retry-http-status" "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted"
  rmdir -- "$ARELAY_ACCOUNT_RETAINED_DIR" || true
  exit 0
fi
if jq -e --arg domain "$ARELAY_ACCOUNT_DOMAIN" \
     'type == "object" and (.registrationId | type == "string" and length > 0) and
      (.accountVerification.workspaceDisplayName | type == "string" and length > 0) and
      (if $domain == "" then .challenge == null else (.challenge | type == "object") end)' \
     "$ARELAY_ACCOUNT_RETAINED_DIR/response.json" >/dev/null 2>&1; then
  echo 'The saved account response looks complete but its HTTP 201 status was not recorded. Preserve every file and stop for support; do not resend or overwrite this response.' >&2
  exit 1
fi
case "$(cat "$ARELAY_ACCOUNT_RETAINED_DIR/http-status" 2>/dev/null || true)" in
  2??)
    echo 'A previous 2xx account response was incomplete. Do not resend, rotate, or remove; stop for support.' >&2
    exit 1
    ;;
esac
[ ! -e "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted" ] || {
  echo 'The retained account request was already retried and may have committed. Do not resend, rotate, or remove; stop for support.' >&2
  exit 1
}
: > "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted"
curl --fail-with-body -sS https://arelay.to/api/v1/registrations \
  -H 'content-type: application/json' --data-binary @"$ARELAY_ACCOUNT_RETAINED_DIR/request.json" \
  --output "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json" --write-out '%{http_code}' \
  > "$ARELAY_ACCOUNT_RETAINED_DIR/retry-http-status"
ARELAY_REQUEST_STATUS=$?
ARELAY_HTTP_STATUS="$(cat "$ARELAY_ACCOUNT_RETAINED_DIR/retry-http-status" 2>/dev/null || true)"
ARELAY_ERROR_CODE="$(jq -r 'if type == "object" then (.code // "") else "" end' "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json" 2>/dev/null || true)"
if [ "$ARELAY_HTTP_STATUS" = 201 ] && \
   jq -e --arg domain "$ARELAY_ACCOUNT_DOMAIN" \
     'type == "object" and (.registrationId | type == "string" and length > 0) and
      (.accountVerification.workspaceDisplayName | type == "string" and length > 0) and
      (if $domain == "" then .challenge == null else (.challenge | type == "object") end)' \
     "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json" >/dev/null 2>&1; then
  cat "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json"
  rm -f -- "$ARELAY_ACCOUNT_RETAINED_DIR/relay.json" "$ARELAY_ACCOUNT_RETAINED_DIR/register.stderr" "$ARELAY_ACCOUNT_RETAINED_DIR/request.json" "$ARELAY_ACCOUNT_RETAINED_DIR/response.json" "$ARELAY_ACCOUNT_RETAINED_DIR/http-status" "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json" "$ARELAY_ACCOUNT_RETAINED_DIR/retry-http-status" "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted"
  rmdir -- "$ARELAY_ACCOUNT_RETAINED_DIR" || true
else
  [ ! -s "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json" ] || cat "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json"
  if jq -e --arg domain "$ARELAY_ACCOUNT_DOMAIN" \
       'type == "object" and (.registrationId | type == "string" and length > 0) and
        (.accountVerification.workspaceDisplayName | type == "string" and length > 0) and
        (if $domain == "" then .challenge == null else (.challenge | type == "object") end)' \
       "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json" >/dev/null 2>&1; then
    echo 'The account retry response looks complete but HTTP 201 was not recorded. Preserve the original and retry files and stop for support; do not resend.' >&2
    exit 1
  fi
  case "$ARELAY_ERROR_CODE" in
    invalid_account_credential)
      rm -f -- "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted"
      echo 'The Cloud credential was rejected. Restart the private device flow, replace only accountCredential in request.json with the block below, then retry once; do not resend unchanged.' >&2
      exit 1
      ;;
    invalid_relay_credential)
      rm -f -- "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted"
      echo 'The delivery credential was rejected. Confirm the intended workspace, rotate arelay-delivery privately, replace only delivery.credential in request.json with the block below, then retry once.' >&2
      exit 1
      ;;
    relay_workspace_not_connected)
      rm -f -- "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted"
      echo 'The active Cloud workspace is not connected to Relay. Stop; connect it, rerun the state and device checks, and refresh both private credentials before retrying.' >&2
      exit 1
      ;;
    relay_workspace_mismatch)
      rm -f -- "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted"
      echo 'The credentials belong to different workspaces. Stop; rerun the state checks, select one intended workspace, and refresh both private credentials before retrying.' >&2
      exit 1
      ;;
  esac
  case "$ARELAY_HTTP_STATUS" in
    2??) echo 'The retry returned an incomplete 2xx response. Do not resend, rotate, or remove; stop for support.' >&2 ;;
    409) if grep -q 'handle_unavailable' "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json"; then
           echo 'The handle is unavailable after an account retry; stop for support. Do not rotate or remove arelay-delivery.' >&2
         else
           rm -f -- "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted"
           echo 'The retry was definitively rejected with HTTP 409; correct public input in the private request and reuse the same credentials.' >&2
         fi ;;
    4??) rm -f -- "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted"
         echo "The retry was definitively rejected with HTTP $ARELAY_HTTP_STATUS; correct public input in the private request and reuse the same credentials." >&2 ;;
    *) echo "The account retry remains ambiguous (HTTP $ARELAY_HTTP_STATUS). Keep the directory and stop for support rather than sending again." >&2 ;;
  esac
  [ "$ARELAY_REQUEST_STATUS" -ne 0 ] && exit "$ARELAY_REQUEST_STATUS"
  exit 1
fi
```

For those four named credential/workspace errors, repair the retained private
request instead of resending it unchanged. Never print either credential.

- `invalid_account_credential`: repeat the device flow into a new mode-0700
  auth directory and replace only `accountCredential` with the validated
  `access_token`.
- `invalid_relay_credential`: after confirming the intended workspace, run
  the isolated `agent-relay agent rotate arelay-delivery` command into a new
  private JSON file and replace only `delivery.credential`.
- `relay_workspace_not_connected`: stop and connect the active Cloud
  workspace to Relay. Do not retry until whoami reports a Relay workspace; the
  rejected request does not count against the account registration quota.
- `relay_workspace_mismatch`: stop and rerun the read-only state checks. Make
  the Cloud active workspace and the workspace containing `arelay-delivery`
  the same, then refresh both credentials. Never work around it with a second
  workspace or delivery identity.

Use this private replacement pattern after obtaining the fresh credential
files. It writes a new request atomically and validates it before replacement:

```bash
set -o pipefail
export ARELAY_ACCOUNT_RETAINED_DIR='/tmp/replace-with-the-printed-directory'
# Set either or both to a real private file after the corresponding refresh flow.
export ARELAY_NEW_CLOUD_SESSION_FILE=
export ARELAY_NEW_RELAY_FILE=

umask 077
[ -f "$ARELAY_ACCOUNT_RETAINED_DIR/request.json" ] || {
  echo 'retained account request not found' >&2
  exit 1
}
[ -n "${ARELAY_NEW_CLOUD_SESSION_FILE:-}" ] || [ -n "${ARELAY_NEW_RELAY_FILE:-}" ] || {
  echo 'set at least one private refresh file; request not changed' >&2
  exit 1
}
cp "$ARELAY_ACCOUNT_RETAINED_DIR/request.json" "$ARELAY_ACCOUNT_RETAINED_DIR/request.next.json" || exit 1
if [ -n "${ARELAY_NEW_CLOUD_SESSION_FILE:-}" ]; then
  jq -e '.access_token | type == "string" and length > 0' "$ARELAY_NEW_CLOUD_SESSION_FILE" >/dev/null || exit 1
  jq --slurpfile fresh "$ARELAY_NEW_CLOUD_SESSION_FILE" '.accountCredential = $fresh[0].access_token' \
    "$ARELAY_ACCOUNT_RETAINED_DIR/request.next.json" > "$ARELAY_ACCOUNT_RETAINED_DIR/request.updated.json" || exit 1
  mv "$ARELAY_ACCOUNT_RETAINED_DIR/request.updated.json" "$ARELAY_ACCOUNT_RETAINED_DIR/request.next.json" || exit 1
fi
if [ -n "${ARELAY_NEW_RELAY_FILE:-}" ]; then
  jq -e '.token | type == "string" and length > 0' "$ARELAY_NEW_RELAY_FILE" >/dev/null || exit 1
  jq --slurpfile fresh "$ARELAY_NEW_RELAY_FILE" '.delivery.credential = $fresh[0].token' \
    "$ARELAY_ACCOUNT_RETAINED_DIR/request.next.json" > "$ARELAY_ACCOUNT_RETAINED_DIR/request.updated.json" || exit 1
  mv "$ARELAY_ACCOUNT_RETAINED_DIR/request.updated.json" "$ARELAY_ACCOUNT_RETAINED_DIR/request.next.json" || exit 1
fi
jq -e '(.accountCredential | type == "string" and length > 0) and (.delivery.credential | type == "string" and length > 0)' \
  "$ARELAY_ACCOUNT_RETAINED_DIR/request.next.json" >/dev/null || exit 1
mv "$ARELAY_ACCOUNT_RETAINED_DIR/request.next.json" "$ARELAY_ACCOUNT_RETAINED_DIR/request.json" || exit 1
rm -f -- "$ARELAY_ACCOUNT_RETAINED_DIR/retry-attempted" "$ARELAY_ACCOUNT_RETAINED_DIR/retry-response.json" "$ARELAY_ACCOUNT_RETAINED_DIR/retry-http-status"
echo 'Private request refreshed. Unset the file variables, delete the refresh files locally, then run the retained account retry once.' >&2
```

Use an address for the company's visitor-answering agent, not the dedicated
delivery identity. Before accepting the workspace badge, arelay.to resolves
the delivery token through Relaycast's authenticated `GET /v1/agent` identity
route and requires its `workspace_id` to equal the active Cloud workspace's
`relay_workspace_id` from whoami.

The credential is encrypted with AES-256-GCM before storage and is never returned by public or management APIs.

The first verification call sends that exact address an ownership DM and returns HTTP 202. The address's agent must reply to that exact message in its Relay thread with the requested challenge line. Retry verification afterward; only then is the handle activated. Visitor messages use the same contract: reply in the incoming message's thread so arelay.to can correlate the response. To rotate the delivery credential, run `env -u RELAY_AGENT_TOKEN -u RELAY_WORKSPACE_KEY -u RELAY_BASE_URL agent-relay agent rotate arelay-delivery` into the same jq/curl pipeline with a management `PATCH`. To revoke access, run the similarly isolated `agent remove` command above; a rejected credential suspends the public profile and chat delivery.

Check whether a published challenge is visible without completing verification:

```bash
curl -sS -H "accept: application/dns-json" \
  "https://cloudflare-dns.com/dns-query?name=_arelay-challenge.acme.com&type=TXT"
curl -sS https://arelay.to/api/v1/registrations/REGISTRATION_ID
```

This read-only response reports `pending`, `verified`, or `expired` and
which challenge was seen. Its `challengeSeen` field is the authoritative
check; the DNS-over-HTTPS request is a useful propagation diagnostic that only
requires curl. The status response never returns a management token.

## 2. Complete verification

Verification returns the management token exactly once. Capture it in a private
file; never print it, paste it into chat, or put it in a URL or browser storage.

```bash
set -o pipefail
export ARELAY_REGISTRATION_ID='REGISTRATION_ID'
umask 077
ARELAY_VERIFY_DIR="$(mktemp -d)" || {
  echo 'could not create private verification directory; verification not requested' >&2
  exit 1
}
trap 'rm -rf "$ARELAY_VERIFY_DIR"' EXIT
echo "Private verification response will be retained at $ARELAY_VERIFY_DIR/response.json until you store its management token." >&2
trap - EXIT
curl --fail-with-body -sS -X POST \
  "https://arelay.to/api/v1/registrations/$ARELAY_REGISTRATION_ID/verify" \
  --output "$ARELAY_VERIFY_DIR/response.json" --write-out '%{http_code}' \
  > "$ARELAY_VERIFY_DIR/http-status"
ARELAY_VERIFY_STATUS=$?
ARELAY_VERIFY_HTTP_STATUS="$(cat "$ARELAY_VERIFY_DIR/http-status" 2>/dev/null || true)"
if [ "$ARELAY_VERIFY_HTTP_STATUS" = 200 ] && \
   jq -e 'type == "object" and (.managementToken | type == "string" and length > 0)' "$ARELAY_VERIFY_DIR/response.json" >/dev/null 2>&1; then
  echo "Verification succeeded. Store the management token directly from $ARELAY_VERIFY_DIR/response.json in the human-approved secret manager without printing it, then delete $ARELAY_VERIFY_DIR." >&2
elif [ "$ARELAY_VERIFY_HTTP_STATUS" = 202 ] && \
     jq -e '.pending == true and .code == "relay_verification_pending" and (.message | type == "string" and length > 0)' "$ARELAY_VERIFY_DIR/response.json" >/dev/null 2>&1; then
  rm -f -- "$ARELAY_VERIFY_DIR/response.json" "$ARELAY_VERIFY_DIR/http-status"
  rmdir -- "$ARELAY_VERIFY_DIR"
  trap - EXIT
  echo "Relay ownership verification was initiated. Wait for the answer agent to reply in the exact ownership-challenge thread, then run verification again." >&2
else
  case "$ARELAY_VERIFY_HTTP_STATUS" in
    4??) echo "Verification was rejected with HTTP $ARELAY_VERIFY_HTTP_STATUS. Check registration status; only if it is still pending should you fix the challenge and retry into this private directory." >&2 ;;
    *) echo "Verification is ambiguous (HTTP $ARELAY_VERIFY_HTTP_STATUS). Keep the private directory and check registration status before any retry." >&2 ;;
  esac
  [ "$ARELAY_VERIFY_STATUS" -ne 0 ] && exit "$ARELAY_VERIFY_STATUS"
  exit 1
fi
```

After any interrupted or ambiguous verify result, first run the same private
`jq` validation against the retained `response.json`. If it contains a
complete `managementToken`, store that token without printing it and clean up.
Otherwise call `GET /api/v1/registrations/REGISTRATION_ID`. If it still
reports `pending`, retry verification into the same private directory. If it
reports `verified` but the file has no complete token, do not retry: stop for
arelay.to support with the handle, registration ID, and HTTP status only. Never
send the private response. arelay.to stores only the token hash.

## 3. Manage the agent

```bash
curl -sS https://arelay.to/api/v1/agents/acme/manage \
  -H 'authorization: Bearer MANAGEMENT_TOKEN'

curl -sS -X PATCH https://arelay.to/api/v1/agents/acme/manage \
  -H 'authorization: Bearer MANAGEMENT_TOKEN' \
  -H 'content-type: application/json' \
  --data '{"description":"Updated description."}'

curl -sS -X POST https://arelay.to/api/v1/agents/acme/rotate-token \
  -H 'authorization: Bearer MANAGEMENT_TOKEN'

curl -sS -X DELETE https://arelay.to/api/v1/agents/acme/manage \
  -H 'authorization: Bearer MANAGEMENT_TOKEN'
```

Public profiles are available at `GET /api/v1/agents/<handle>`. They report
`verificationMethod` as `domain`, `account`, or `both`, plus the
applicable verified domain and/or Agent Relay workspace display name. Domain
ownership is checked again every 30 days; a failed check suspends delivery and
is retried daily so restoring the proof restores service automatically.