> ## 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.

# Register a DID

> Submit a new public DID record.

Submit a new public DID record.

<Note>
  The Directory submits `register_with_document_proof` as an ownerless DID-key operation. It does not attach a
  chain account owner, even if the server environment contains an account seed.
</Note>

Registration creates the first public record for an identity. Your client signs the UTF-8 text `DID|timestamp` with the Ed25519 private key corresponding to the submitted root public key.

## Request

<ParamField body="did" type="string" required>
  The canonical `did:<platform>:<Base58Address>` identifier. The platform must contain 1–32 lowercase ASCII letters or digits. The address must contain 16–96 Bitcoin Base58 characters. The identifier must exactly match `did_document.id`.
</ParamField>

<ParamField body="timestamp" type="string" required>
  The timestamp included in the signed request.
</ParamField>

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

<ParamField body="did_document" type="object" required>
  The public DID document.
</ParamField>

<ParamField body="root_pubkey" type="string">
  The root Ed25519 public key. The first verification method supplies it when omitted.
</ParamField>

<ParamField body="alias" type="string">
  An optional lowercase public alias. It cannot contain `@` or `#`.
</ParamField>

<RequestExample>
  ```bash Request theme={null}
  curl --request POST \
    --url "https://directory.example.com/register-did" \
    --header "Content-Type: application/json" \
    --data '{
    "did": "did:openpayload:1111111111111111111111",
    "timestamp": "2026-07-16T12:00:00Z",
    "signature": "<signature>",
    "root_pubkey": "z<ed25519-public-key>",
    "did_document": {
      "id": "did:openpayload:1111111111111111111111",
      "verificationMethod": [
        {
          "id": "did:openpayload:1111111111111111111111#keys-1",
          "type": "Ed25519VerificationKey2020",
          "controller": "did:openpayload:1111111111111111111111",
          "publicKeyMultibase": "z<ed25519-public-key>"
        }
      ],
      "authentication": [
        "did:openpayload:1111111111111111111111#keys-1"
      ],
      "keyAgreement": [
        {
          "id": "did:openpayload:1111111111111111111111#x25519-1",
          "type": "X25519KeyAgreementKey2020",
          "controller": "did:openpayload:1111111111111111111111",
          "publicKeyMultibase": "z<x25519-public-key>"
        }
      ],
      "service": [
        {
          "id": "did:openpayload:1111111111111111111111#relay",
          "type": "OpenPayloadRelayService",
          "serviceEndpoint": ["https://relay.example.com"]
        },
        {
          "id": "did:openpayload:1111111111111111111111#cache",
          "type": "OpenPayloadCacheService",
          "serviceEndpoint": ["https://cache.example.com"],
          "authorization": [
            "did:openpayload:1111111111111111111111#keys-1"
          ]
        }
      ]
    }
  }'
  ```
</RequestExample>

## Response

<ResponseField name="status" type="string" required>
  A human-readable registration status.
</ResponseField>

<ResponseField name="registration_status" type="string" required>
  The public registration state.
</ResponseField>

<ResponseField name="tx_id" type="string" required>
  The submitted transaction identifier.
</ResponseField>

<ResponseField name="did" type="string" required>
  The submitted DID.
</ResponseField>

<ResponseField name="did_document" type="object" required>
  The submitted public DID document.
</ResponseField>

<ResponseExample>
  ```json 202 Response theme={null}
  {
    "status": "did registration pending",
    "registration_status": "pending",
    "tx_id": "<transaction-id>",
    "did": "did:openpayload:1111111111111111111111",
    "did_document": {
      "id": "did:openpayload:1111111111111111111111",
      "verificationMethod": [
        {
          "id": "did:openpayload:1111111111111111111111#keys-1",
          "type": "Ed25519VerificationKey2020",
          "controller": "did:openpayload:1111111111111111111111",
          "publicKeyMultibase": "z<ed25519-public-key>"
        }
      ],
      "authentication": [
        "did:openpayload:1111111111111111111111#keys-1"
      ],
      "keyAgreement": [
        {
          "id": "did:openpayload:1111111111111111111111#x25519-1",
          "type": "X25519KeyAgreementKey2020",
          "controller": "did:openpayload:1111111111111111111111",
          "publicKeyMultibase": "z<x25519-public-key>"
        }
      ],
      "service": [
        {
          "id": "did:openpayload:1111111111111111111111#relay",
          "type": "OpenPayloadRelayService",
          "serviceEndpoint": ["https://relay.example.com"]
        },
        {
          "id": "did:openpayload:1111111111111111111111#cache",
          "type": "OpenPayloadCacheService",
          "serviceEndpoint": ["https://cache.example.com"],
          "authorization": [
            "did:openpayload:1111111111111111111111#keys-1"
          ]
        }
      ]
    }
  }
  ```
</ResponseExample>

<Note>
  `202` means the Directory accepted the registration for processing. It does not confirm final settlement.
  Poll [Get registration status](/api-reference/directory/dids/registration-status) until the state is `confirmed`.
</Note>

<Card title="Understand the complete document" icon="file-code" href="/concepts/complete-did-document">
  Learn how each key and service entry participates in encryption, Relay delivery, and Cache retrieval.
</Card>

## Straight to the point

```http theme={null}
POST /register-did
Content-Type: application/json
```

* Signed bytes: UTF-8 `did + "|" + timestamp`
* Signature: Ed25519, Base64 encoded
* Private key: never submitted
* Confirmation: poll `GET /registration-status/{did}`


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