DIDs — did:iota vs did:key

A Decentralized Identifier (DID) is a globally unique identifier that resolves to a public key without depending on any single registrar. In TCS, DIDs answer a simple question: who is this entity, and how do I verify a signature they produced?

TCS supports two DID methods. The choice is not aesthetic — each has a different cost model, trust model, and lifecycle.

What a DID actually is

A DID looks like did:method:identifier:

did:iota:tst:0xabc...           ← published on the IOTA Tangle
did:key:z6Mki...                ← key material encoded in the identifier itself

Resolving a DID returns a DID Document — JSON with the public keys and metadata associated with that DID. A verifier resolves the issuer’s DID, retrieves the public key, and checks the credential signature against it.

The method part determines how resolution happens. That is the entire substance of the choice between methods.

did:iota — anchored, mutable, public

did:iota publishes the DID Document to the IOTA Tangle. The identifier points at a transaction; resolving it pulls the latest published DID Document from the network.

Properties:

On-chain anchor. Once published, the identifier is unique and globally resolvable.
Rotatable keys. The DID Document can be updated to add, remove, or rotate keys without changing the identifier itself. Old credentials remain verifiable as long as their signing key is preserved in the document’s history (or kept active).
Public discovery. Anyone with the DID can resolve it. There is no permission layer at the DID level — trust is layered on top via the Trust Registry.
Algorithm. TCS issues with EdDSA for did:iota. Signatures carry a kid referencing a key in the DID Document.
Cost. Publishing or updating a DID Document is a Tangle transaction.

Use did:iota when:

You are an issuer and need a stable, public identity that survives key rotation.
You will register in the Trust Registry — verifiers expect a resolvable issuer DID.
You need credentials to remain verifiable for a long time independent of any single server.

did:key — self-contained, immutable, ephemeral

did:key encodes the public key directly inside the identifier. There is no document to publish — the DID is the key.

Properties:

No registration required. Generate a keypair, encode the public key, and you have a DID. Zero infrastructure.
Immutable. The key cannot rotate without producing a new DID. There is no “update”.
Self-contained resolution. Anyone who can parse the identifier can derive the public key. No network call.
Algorithm. TCS generates did:key with ES256 (P-256). HAIP-conformant flows that require ES256 (e.g. holder key binding on the X.509 / x5c issuer path) align naturally with this choice.
Cost. None.

Use did:key when:

You want a holder identity without a Tangle transaction or any registration step.
You want per-credential or per-session key rotation — generating a new did:key for each credential is cheap and gives strong unlinkability.
You need a throwaway identity for a short-lived flow (testing, demos, ephemeral interactions).

Side-by-side

Property	`did:iota`	`did:key`
Resolution	IOTA Tangle	Decode from identifier
Mutable	Yes (key rotation)	No (immutable)
Network required to resolve	Yes	No
Registration cost	Tangle transaction	None
Signing algorithm in TCS	EdDSA	ES256 (P-256)
Stable across key rotation	Yes	No
Privacy	Public	Pseudonymous (per-instance)

Where DIDs fit in TCS

Role	Supported methods	Algorithm	Where the DID appears
Issuer (DID path)	`did:iota`	EdDSA	`kid` in credential signature; resolved via Trust Registry
Issuer (X.509 path)	(no DID — uses X.509 cert chain)	ES256	`x5c` header; HAIP-conformant path
Holder (custodial — Holder Service)	`did:iota`	EdDSA	Key-binding JWT during presentation
Holder (non-custodial — external wallet)	`did:iota` or `did:key`	EdDSA / ES256	Key-binding JWT during presentation

Issuers must use a stable, public identity, so did:iota (or X.509) is required. The X.509 path (ES256 with an x5c certificate chain) is required for HAIP profile compliance — see Architecture & Security for when to choose X.509 over did:iota.

Holders depend on the operating mode:

Custodial mode — Holder Service provisions a did:iota per end user. did:key is not provisioned by Holder Service for binding; the POST /v1/did endpoint accepts method: "IOTA" only.
Non-custodial mode — the wallet generates its own keys. Wallets implementing OID4VP key binding may use did:iota or did:key (ES256) — TCS does not constrain the choice on the verifier side, beyond standard signature validation.

Key rotation and compromise — what’s actually possible today

A direct answer for security reviewers, because the docs above intentionally don’t gloss this:

Key rotation on did:iota is supported. The DID Document on the Tangle can be updated to add a new key and remove the old one; the DID identifier itself does not change, and credentials signed under the old key remain verifiable as long as the old key is preserved in the DID Document’s history.
Credential-level revocation is not yet exposed publicly. Per Standards Compliance · Roadmap, the IETF Token Status List is on the roadmap. Until then, rotating an issuer key prevents future abuse; it does not retroactively invalidate credentials already signed by a leaked key.
No public key-rotation runbook exists yet. If an issuer key is suspected compromised, contact the TCS team — the rotation procedure (DID Document update + Tangle confirmation + verifier cache flush window) is currently handled out of band.

This is the honest blast-radius picture: rotation contains forward risk; status-list-grade revocation does not yet exist; emergency procedures go through TCS support.

What’s next

Verifiable Credentials — how a DID participates in credential signing
Trust & Governance — how the Trust Registry binds DIDs to organizations
Standards Compliance — algorithm requirements per profile (HAIP, OID4VCI)