---
title: "Track an externally-managed DID"
method: POST
path: "/identifiers/external"
tags: ["Dids"]
---

# Track an externally-managed DID

`POST /identifiers/external`

Registers a reference to an externally-managed DID for local tracking.
Only the DID string (and optional alias) is persisted; the resolver
fetches the document and the IDK CacheService holds it. The tracked
DID always gets `role = EXTERNAL`. KMS key material is never bound to
external DIDs; keys belong to MANAGED DIDs created locally via
`POST /identifiers`.

## Parameters

- `./common-components.yml#/components/parameters/CorrelationId` — unresolved $ref

## Request body

- TrackExternalDidRequest — Request body for tracking an externally-managed DID. Only the DID string and an optional alias are accepted; the server resolves the document and caches it via the IDK CacheService. KMS bindings, inline document payloads, and key mappings are deliberately omitted: external DIDs are tracked as the string only and never carry locally managed key material.
  - `did` string, required — The external DID string to track.
  - `alias` string — Optional human-readable alias.

## Response `201`

External DID reference created successfully.

- Did — unresolved $ref

## Other responses

- `400` — unresolved $ref
- `401` — unresolved $ref
- `403` — unresolved $ref
- `409` — unresolved $ref
- `500` — unresolved $ref

---

[API](https://skmtc.dev/sphereon-opensource/apis/did-rest-api.md) · [All operations](https://skmtc.dev/sphereon-opensource/apis/did-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sphereon-opensource/did-rest-api/revisions/d575fc307e80/schema)