> 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 covers the end points related to DIDs in the API

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.