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

# Authorize a Directory update

> A beginner-friendly guide to nonces, canonical payloads, and signatures

Read-only requests do not require your private key. Updates do, because a Directory must distinguish the DID controller from somebody merely claiming to be the controller.

Authorization happens entirely on your device:

1. Read the current nonce.
2. Build the operation's canonical payload.
3. Sign the exact payload bytes with an authorized Ed25519 key.
4. Send the public fields, encoded payload, and signature.

The Directory receives no private key.

## Nonces prevent replay

A nonce is a counter associated with a DID authorization domain. Once a nonce is used successfully, another request cannot safely reuse it.

Fetch current values with:

```http theme={null}
GET /dids/{did}/nonces
```

Use the nonce named for the operation you are building. If another update is submitted first, fetch the values again and rebuild the signature.

## Expiration limits stolen requests

`valid_until` is an unsigned 64-bit Unix timestamp in **milliseconds** for SCALE authorization payloads. Use a short future window and make sure the machine signing the request has an accurate clock.

## Canonical payloads are bytes

For DID-document component operations, `canonical_payload` is the exact SCALE-encoded authorization structure. Send it as:

* Hex beginning with `0x`, or
* Standard or URL-safe Base64

The Directory decodes the value, reconstructs the expected structure from the other request fields, and compares the bytes. Signing a JSON object or a visually similar string will not work.

The document authorization field order is:

| Position | SCALE value                         |
| -------- | ----------------------------------- |
| 1        | DID as `Vec<u8>` UTF-8              |
| 2        | action discriminant as `u8`         |
| 3        | optional verification method        |
| 4        | optional key-agreement method       |
| 5        | optional service                    |
| 6        | optional component ID               |
| 7        | nonce as `u64`                      |
| 8        | `valid_until` as `u64` milliseconds |
| 9        | signer key ID as `Vec<u8>` UTF-8    |

Each endpoint page identifies which optional item is populated.

<Warning>
  Alias authorization is temporarily unavailable as a stable cross-client contract while its runtime SCALE payload is synchronized. Do not build production alias mutation signing from the current JSON placeholder.
</Warning>

## Sign the bytes, not their printed encoding

If `canonical_payload` is Base64, decode it and sign the decoded bytes. Do not sign the Base64 characters. The resulting Ed25519 signature is sent as Base64 in `signature`.

## Signer selection

Set `signer_key_id` to:

* `root` to use the record's root public key, or
* A complete authorized verification-method ID such as `did:talaria:...#signing`

The key must already be authorized by the DID record.

## Why the body repeats the DID and action

The path selects the resource. The signed body binds the authorization to the same DID and one exact operation. The Directory rejects a mismatch rather than guessing what the caller intended.

## Straight to the point

```text theme={null}
nonce = GET /dids/{did}/nonces
payload = SCALE(operation fields in documented order)
signature = Ed25519.sign(private_key, payload_bytes)
canonical_payload = "0x" + hex(payload_bytes)
```

Never send `private_key`, a mnemonic, or a seed phrase.