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

# Update an alias

> Replace an existing public alias.

Replace an existing public alias.

This operation atomically replaces `old_alias` with `new_alias`; it is not two independent requests.

## Path parameters

<ParamField path="did" type="string" required>
  The DID that owns the alias.
</ParamField>

<ParamField path="oldAlias" type="string" required>
  The existing alias.
</ParamField>

## Request body

<ParamField body="did" type="string" required>
  The DID that owns the alias. It must match the path.
</ParamField>

<ParamField body="action" type="string" required>
  The operation name. Use `update_alias`.
</ParamField>

<ParamField body="old_alias" type="string" required>
  The existing alias. It must match the path.
</ParamField>

<ParamField body="new_alias" type="string" required>
  The lowercase replacement alias. It cannot contain `@` or `#`; those characters are reserved for delivery-target and DID-document syntax.
</ParamField>

<ParamField body="nonce" type="string" required>
  The request nonce.
</ParamField>

<ParamField body="valid_until" type="string" required>
  The authorization expiration as an ISO-8601 timestamp or unsigned Unix-millisecond string. The canonical payload encodes it as `u64` milliseconds.
</ParamField>

<ParamField body="signer_key_id" type="string">
  The public signing-key identifier. Defaults to `root`.
</ParamField>

<ParamField body="canonical_payload" type="string" required>
  The canonical SCALE `AliasAuthorizationPayload`, encoded as `0x`-prefixed hex or Base64.
</ParamField>

<ParamField body="signature" type="string" required>
  The authorization signature.
</ParamField>

<RequestExample>
  ```bash Request theme={null}
  curl --request PATCH \
    --url "https://directory.example.com/dids/did%3Aopenpayload%3A1111111111111111111111/aliases/river.stone" \
    --header "Content-Type: application/json" \
    --data '{
    "did": "did:openpayload:1111111111111111111111",
    "action": "update_alias",
    "old_alias": "river.stone",
    "new_alias": "river.rock",
    "nonce": "<nonce>",
    "valid_until": "<future-epoch-milliseconds>",
    "signer_key_id": "root",
    "canonical_payload": "<payload>",
    "signature": "<signature>"
  }'
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string" required>The submission status.</ResponseField>
<ResponseField name="did" type="string" required>The affected DID.</ResponseField>
<ResponseField name="action" type="string" required>The alias operation.</ResponseField>
<ResponseField name="tx_hash" type="string" required>The transaction hash.</ResponseField>
<ResponseField name="message" type="string" required>A human-readable submission result.</ResponseField>

<ResponseExample>
  ```json 202 Response theme={null}
  {
    "status": "accepted",
    "did": "did:openpayload:1111111111111111111111",
    "action": "update_alias",
    "old_alias": "river.stone",
    "new_alias": "river.rock",
    "tx_hash": "<transaction-hash>",
    "message": "Alias update submitted"
  }
  ```
</ResponseExample>

<Note>
  `202 Accepted` means the Directory accepted the request for processing. It does not confirm final settlement.
</Note>

## Straight to the point

* Method: `PATCH`
* Action: `update_alias`
* Path alias must equal `old_alias`
* New alias cannot contain `@` or `#`
* Signed payload: canonical SCALE alias authorization bytes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.