> For the complete documentation index, see [llms.txt](https://guide.transmute.industries/verifiable-data-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.transmute.industries/verifiable-data-platform/technical-documentation/decentralized-identifiers-endpoints.md).

# Decentralized Identifiers Endpoints

This page introduces working with Decentralized Identifiers through the API. The full set of relevant endpoints are listed on the OpenAPI Spec, notably in this section: 

<https://platform.transmute.industries/openapi#tag--Identifiers>

## Managing Decentralized Identifiers

Allows management of common Decentralized Identifiers methods `did:web`. Any new organization is born with a DID which can be queried with `GET /organizations`:

```
curl --location --request GET 'https://platform.transmute.industries/api/organizations' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### **Resolving a DID Document**

All of the returned of DIDs, like any DID, can be resolved to a *DID Document*. `GET /identifiers/{did}` resolves a DID:

```
curl --location --request GET 'https://platform.transmute.industries/api/identifiers/did:web:...' \
--header 'Accept: application/json'
```

Replace `did:web:...` with one of the `did`s returned from `GET /did/identifiers` to resolve one of your own organization’s DIDs. Note that this can also be your organization’s `did:web`:

```
curl --location --request GET 'https://platform.transmute.industries/api/organizations/{{organizationId}}/did.json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### **Understanding DID Documents**

```
{
  "didDocument": {
    "@context": [
      "https://www.w3.org/ns/did/v1",
      "https://w3id.org/security/suites/jws-2020/v1"
    ],
    "id": "did:key:z6MkjcrxZHykMdAQBv4tqyayg2caVET2bgdj5iiM8V8yseXK",
    "verificationMethod": [
      {
        "id": "did:key:z6MkjcrxZHykMdAQBv4tqyayg2caVET2bgdj5iiM8V8yseXK#z6MkjcrxZHykMdAQBv4tqyayg2caVET2bgdj5iiM8V8yseXK",
        "type": "JsonWebKey2020",
        "controller": "did:key:z6MkjcrxZHykMdAQBv4tqyayg2caVET2bgdj5iiM8V8yseXK",
        "publicKeyJwk": {
          "kty": "OKP",
          "crv": "Ed25519",
          "x": "TMAjbsE9aeFO9oECIX3MI1QtGawnEYOJawl-lxwa1kI"
        }
      }
    ],
    "assertionMethod": [
      "did:key:z6MkjcrxZHykMdAQBv4tqyayg2caVET2bgdj5iiM8V8yseXK#z6MkjcrxZHykMdAQBv4tqyayg2caVET2bgdj5iiM8V8yseXK"
    ],
    "authentication": [
      "did:key:z6MkjcrxZHykMdAQBv4tqyayg2caVET2bgdj5iiM8V8yseXK#z6MkjcrxZHykMdAQBv4tqyayg2caVET2bgdj5iiM8V8yseXK"
    ]
  }
}
```

The DID Document which we just resolved (or the example listed above) includes everything which the public needs to know in order to verify that your organization controls a given DID.

DID Documents typically includes one or more public keys, listed in the `verificationMethod` array. Each of these public keys are paired with a private key which is kept on the platform as an organization secret.

Keys are used to allow others to verify that certain actions are indeed done by a private key holder, and thereby by a DID. Keys are formally referred to as “Verification Methods”; their relationship to the DID are referred to as “Verification Relationships”. Examples of such verification relationships include issuance of Verifiable Credentials (keys listed in the `assertionMethod` array) and making Verifiable Presentations (keys listed in the `authentication` array). There is a many-to-many relationship between keys and the verification relationships which they can be used to perform; the `id` of the `verificationMethod`s used to associate which keys are used for what. The format of this id is known as a `DID-URL` and always consists of the DID itself (which is in the root `id` follow by a `#` and an internal key-identifier.