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

# Resolve & verify a DID

> Resolve a DID to its current state and verify it cryptographically — the signature, the transparency-log inclusion proof, and the content integrity — through public, read-only endpoints.

Anyone can resolve a DID and verify it without logging in. The verification
endpoints are **public** and **read-only**, so a third party — a reviewer, a
funder, a downstream researcher — can confirm a record is authentic for
themselves.

Replace `$DATAERAI_SERVER` with your Dataerai host in the examples below.

## Resolve a DID

```bash theme={null}
curl $DATAERAI_SERVER/api/identity/resolve/did:dataerai:asset:3diw…/
```

Resolving returns the DID's current state — its kind, status, visibility, and a
**verification** result. A resolved record reports `verified: true` only when
both checks below pass.

The `status` field describes the record's lifecycle:

| `status`      | Meaning                                                                          |
| ------------- | -------------------------------------------------------------------------------- |
| `active`      | The record is live and current.                                                  |
| `superseded`  | The record was merged into another; `superseded_by` points to the survivor.      |
| `deactivated` | The record was deleted; it resolves as a **tombstone** so citations don't break. |

The response also reports `visibility` (`public` or `private`) and `gated`
(whether reading the DID requires access). A **public** DID resolves for anyone;
a **private/gated** DID has no anonymous surface (see below).

## What "verified" means

| Check               | Question it answers                                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Signature**       | Did Dataerai sign this record? The signature is checked against the [published keys](#verification-keys).                            |
| **Inclusion proof** | Is this record really in the transparency log, where it claims to be? The proof is checked against a **signed snapshot** of the log. |

When both hold, the record is provably authentic and provably logged — it cannot
have been forged or quietly inserted after the fact.

## Public endpoints

| Endpoint                                   | Purpose                                                                                                           |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `GET /api/identity/resolve/{did}/`         | Resolve a DID to its current state and verification result.                                                       |
| `GET /api/identity/{did}/document/`        | The public `did:web` document for a **published** DID (a private DID reports it isn't published, never an error). |
| `GET /api/identity/{did}/verify/`          | Verify the DID's signature and inclusion proof.                                                                   |
| `POST /api/identity/{did}/verify-content/` | Confirm the record's **content** still matches what was signed.                                                   |
| `GET /api/identity/{did}/log/`             | The signed, append-only history of edits to the record.                                                           |
| `GET /api/identity/keys/`                  | The published Ed25519 public keys used to verify.                                                                 |

## Verify content integrity

A DID commits to the record's **content**, not just its metadata. The
`verify-content` endpoint confirms the file content has not changed since it was
signed — so you can prove a dataset is byte-for-byte what it was when you cited
it.

## Verification keys

`GET /api/identity/keys/` returns the public keys anyone uses to verify. Keys can
**rotate** over time; records signed under an earlier key keep verifying, because
each record records which key signed it.

<Note>
  Verification is **fail-closed**: an unknown or misconfigured key never silently
  downgrades the result to "verified." If a record cannot be proven authentic, it
  is reported as unverified.
</Note>

## The audit log

`GET /api/identity/{did}/log/` returns the record's full history — its creation
and every edit since — as a signed, append-only chain. Each entry is part of the
same tamper-evident log, so the history itself is verifiable, not just the
current state.

## Gated DIDs and access

A **private (gated)** DID has no anonymous public surface. An anonymous caller —
or anyone without access — who resolves a gated DID gets a **404**, the same
response as an unknown DID, so the endpoints never leak whether a private record
exists. People who can already read the record (the owner and anyone it's shared
with) resolve and verify it normally.

### Share a gated DID

To let an external reviewer verify a gated DID **without publishing it**, the
record's creator or an admin can mint a time-boxed **read capability** for that
one DID:

```bash theme={null}
curl -X POST $DATAERAI_SERVER/api/identity/{did}/capability/ \
  -H "Authorization: Bearer $DATAERAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 3600}'
```

`ttl` is the lifetime in seconds (capped by the server). The response returns a
`capability` token. The reviewer passes it on any resolve or verify request —
either as a header or a `cap` query parameter — to unlock just that one DID:

```bash theme={null}
curl -H "X-Identity-Capability: <token>" \
  $DATAERAI_SERVER/api/identity/resolve/{did}/
```

The token grants read and verify access to that single DID only, and it expires.
Replace `$DATAERAI_SERVER` with your host and `$DATAERAI_TOKEN` with an OAuth2
access token — see [Authentication](/api-reference/authentication).

## Next steps

<CardGroup cols={2}>
  <Card title="Publish & cite" icon="globe" href="/identity/publish-and-cite">
    Make a DID public and get its `did:web` document for citation.
  </Card>

  <Card title="Provenance tokens" icon="shield-check" href="/organize/provenance-tokens">
    The other signed artifact on every asset — who created it.
  </Card>
</CardGroup>