DIDs API

What is a DID?

A Decentralized Identifier (DID) is a globally unique identifier that you control, backed by a cryptographic key pair. Unlike traditional identifiers (email, username), a DID doesn’t depend on a central authority — you prove ownership by signing with the private key.

In BaseID Cloud, DIDs serve as your issuer identity. When you issue a credential, the DID’s private key produces the signature that verifiers use to confirm authenticity.

Example DID:

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

The did:key method encodes the public key directly in the identifier — no external infrastructure needed to resolve it.

---

Key types

When creating a DID, you choose a cryptographic key type. This determines the signature algorithm used when issuing credentials.

Key type	Algorithm	Signature	Key size	Best for
Ed25519	EdDSA	64 bytes	32 bytes	General purpose. Fastest signatures, smallest keys. Recommended default.
P-256	ES256	64 bytes	33 bytes	WebAuthn/FIDO2 compatibility. Apple/Google attestation. NIST-approved.
P-384	ES384	96 bytes	49 bytes	Higher security margin. Government standards (HAIP profile). Some enterprise procurement requires ES384+.

Which key type should I choose?

• Start with Ed25519 unless you have specific requirements. It’s the fastest and most compact, supported by all major verifiable credential libraries.
• Use P-256 if integrating with WebAuthn, FIDO2, Apple Attestation, or systems that mandate NIST P-256 (ES256).
• Use P-384 if targeting the HAIP profile, government procurement requiring ES384, or environments with elevated security requirements.

All three key types produce credentials that are interoperable with standard W3C VC and SD-JWT verifiers.

---

Create a DID

POST /v1/dids
Authorization: Bearer <token>

Permission required: dids:create

Request body

Field	Type	Default	Description
method	string	key	DID method. Currently key (self-contained, no infrastructure).
key_type	string	Ed25519	Cryptographic key type: Ed25519, P256, P384

Example

curl -X POST https://api.baseid.cloud/v1/dids \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"method": "key", "key_type": "Ed25519"}'

Response

{
  "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "method": "key",
  "key_type": "Ed25519"
}

What happens when you create a DID

1. A new key pair is generated server-side using a cryptographically secure random number generator
2. The private key is stored encrypted in your tenant’s database
3. The public key is encoded into the DID identifier
4. The DID is immediately usable for issuing credentials

Plan limits

Plan	Max DIDs
Developer (free)	1
Startup ($49)	5
Business ($199)	25
Enterprise	Unlimited

---

List DIDs

GET /v1/dids
Authorization: Bearer <token>

Permission required: dids:list

Returns only active (non-deactivated) DIDs belonging to your tenant.

Response

[
  {
    "did": "did:key:z6Mk...",
    "method": "key",
    "created_at": "2026-03-26T12:00:00Z",
    "deactivated": false
  }
]

---

Resolve a DID

Resolve any DID to its DID Document. This works for any did:key DID, not just your tenant’s — useful for inspecting an issuer’s public keys.

GET /v1/dids/:did
Authorization: Bearer <token>

Permission required: dids:list

The :did parameter must be URL-encoded:

/v1/dids/did%3Akey%3Az6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

Response — DID Document

{
  "id": "did:key:z6Mk...",
  "verificationMethod": [
    {
      "id": "did:key:z6Mk...#z6Mk...",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:key:z6Mk...",
      "publicKeyMultibase": "z6Mk..."
    },
    {
      "id": "did:key:z6Mk...#z6LSk...",
      "type": "JsonWebKey2020",
      "controller": "did:key:z6Mk...",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "..."
      }
    }
  ],
  "authentication": ["did:key:z6Mk...#z6Mk..."],
  "assertionMethod": ["did:key:z6Mk...#z6Mk..."]
}

DID Document fields

Field	Description
id	The DID itself
verificationMethod	Array of public keys associated with this DID
authentication	Key IDs authorized for authentication
assertionMethod	Key IDs authorized for signing assertions (credentials)
publicKeyJwk	The public key in JSON Web Key format (used for verification)

---

Deactivate a DID

Permanently deactivate a DID. Use this for key rotation or when retiring an identity.

DELETE /v1/dids/:did
Authorization: Bearer <token>

Permission required: dids:deactivate

What happens when you deactivate

Aspect	Effect
New issuance	Blocked — cannot issue credentials with this DID
Existing credentials	Remain valid — verifiers can still check signatures
Key material	Preserved but marked inactive — not deleted
Reversibility	Permanent — cannot be reactivated
DID resolution	Still resolvable — public key available for verification

Response

{
  "status": "deactivated",
  "did": "did:key:z6Mk..."
}

When to deactivate

• Key rotation: Create a new DID with fresh keys, then deactivate the old one
• Compromised key: If you suspect the private key was exposed
• Organizational change: When an issuer identity is no longer needed

---

DID methods roadmap

Method	Status	Description
did:key	Available	Self-contained, no infrastructure. Public key in the identifier.
did:web	Planned	Domain-based DID resolved via HTTPS. Ties identity to a domain name.
did:peer	Planned	Peer-to-peer DIDs for DIDComm. No public resolution.
did:webvh	Planned	Verifiable history — trust over time with signed updates.

---

See also

• DIDs concept — methods, resolution, key types, lifecycle
• Credential Formats concept — how DIDs sign different formats
• Console: DIDs — dashboard guide
• Security Model — key storage and encryption