> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didx.co.za/llms.txt
> Use this file to discover all available pages before exploring further.
# Credentials
> Decentralized Identifiers, verifiable credentials, the two formats didx:me supports, and selective disclosure.
## Decentralized Identifiers (DIDs)
A DID is a globally unique identifier that isn't owned by a single platform. Unlike an email address (controlled by your email provider) or a phone number (controlled by your telco), a DID is controlled by whoever holds its cryptographic keys.
Every issuer, holder, and verifier on didx:me has at least one DID. When a credential is issued, the issuer's DID and the holder's DID are both bound into it cryptographically.
didx:me currently uses the `did:web` method. You don't manage DIDs by hand, the platform mints and resolves them for you. You'll see them in API responses and credential payloads.
## Verifiable Credentials
A verifiable credential is a set of claims about a subject, signed by an issuer, held by the subject, and presentable to anyone who needs to verify the claims are authentic and unmodified. For example:
> *"The holder of DID X is a registered student at University Y, enrolled on 2024-02-01."*
Four properties make that statement *verifiable*:
1. **Tamper-evident**, any change to the data breaks the signature.
2. **Issuer-authenticated**, anyone can check which issuer signed it, and that the signature is valid.
3. **Holder-bound**, the credential is tied to a specific holder's DID, so it can't be replayed by someone else.
4. **Cryptographically self-contained**, the credential carries everything needed to verify it. No call back to the issuer is required to confirm authenticity.
That last property is what separates a verifiable credential from a traditional API lookup. A bank can check a student card's authenticity without asking the university whether the credential is real. (On didx:me you'll still call our API to *receive* and *parse* a presentation, the "self-contained" property is about cryptographic trust, not about bypassing the platform.)
## Credential formats
didx:me supports two credential formats. You choose the format when you create a credential template, and the choice flows through the rest of the lifecycle.
| Format | Format value in the API | When to use |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **SD-JWT VC** | `sd-jwt` at template creation (`credentialFormat`); `sd-jwt-vc` in presentation flows (`format`). The two values refer to the same format — the duplication is a known spec inconsistency under engineering review. | Most general-purpose use. Holder-friendly wallet support, JSON-native payloads, rich selective disclosure. |
| **mDoc** | `mdoc` | Regulated / mobile-driving-licence-adjacent use cases. Required when a counterparty (regulator, government wallet, specific sector requirement) mandates it. |
In prose, this guide refers to the format as **SD-JWT VC**. In code samples and API payloads, the literal string `sd-jwt-vc` (or `sd-jwt` at template creation) is used, matching what the API returns.
For the specifications these formats implement, see [Standards and specifications](/products/didx-me/getting-started/standards-and-specs).
Both formats support selective disclosure through different mechanisms. SD-JWT VC uses salted per-claim disclosures that the holder releases individually. mDoc uses a signed Mobile Security Object in which each data element is independently digested, so the holder can release any subset of elements while keeping the issuer's signature intact. Both can be held in compatible wallets. The practical difference is the encoding family: SD-JWT VC is JSON-based; mDoc is CBOR-based.
SD-JWT VC is the default for most integrations. Pick mDoc only when a counterparty (regulator, government wallet,
specific sector standard) requires it.
## Selective disclosure
Both formats let the *issuer sign once* and the *holder choose later* which attributes a given verifier sees. That's the mechanism behind privacy claims like "share that you're over 18 without sharing your date of birth", the credential contains both; the holder reveals only the derived claim.
The `alwaysDisclosed` flag applies to **SD-JWT VC credentials only**. mDoc has no equivalent issuer-side flag: under ISO 18013-5, every data element is independently disclosable by default, and the choice of which elements to release sits with the holder's wallet at presentation time. There is no template-level switch the issuer can use to force a given mDoc element to always be disclosed — if a verifier needs guaranteed disclosure of a specific element, that's a property of the verifier's request, not the issuer's template.
When you design an SD-JWT VC credential template, every attribute has an `alwaysDisclosed` flag:
| Flag value | Behaviour | Use for |
| ------------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `alwaysDisclosed: true` | The attribute is always revealed when the credential is presented. The holder cannot withhold it. | Attributes the verifier *must* see, credential type, issuance date, issuer identifier |
| `alwaysDisclosed: false` | The holder can choose whether to share or withhold the attribute on a per-presentation basis. | Everything else. **This is the default.** |
Default to `alwaysDisclosed: false` unless you have a concrete reason the verifier needs the attribute in every
presentation. Every attribute you mark `true` is a small reduction in the user's privacy surface.