> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yoid.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials Explained

> How verifiable credentials work in the YOMA ecosystem — without the jargon.

## What is a Verifiable Credential?

A verifiable credential is a digital equivalent of a paper certificate — cryptographically signed, tamper-proof, and instantly verifiable by anyone the holder chooses to share it with.

## The Three Roles

Every credential interaction involves three participants:

<Steps>
  <Step title="Issuer creates and signs the credential">
    A learning partner, impact partner, or government body creates a credential from a template and issues it to a youth. The credential is cryptographically signed — proving who issued it and that it hasn't been tampered with.
  </Step>

  <Step title="Holder receives and controls the credential">
    The youth receives the credential in their digital wallet. They decide who to share it with, when, and which specific attributes to reveal. This is **selective disclosure** — a core feature, not an afterthought.
  </Step>

  <Step title="Verifier requests and validates the credential">
    An employer or opportunity provider creates a verification request specifying what they need to see. The youth's wallet prompts them for consent. If they agree, the verifier receives cryptographic proof of the credential's authenticity.
  </Step>
</Steps>

## Selective Disclosure

Each attribute in a credential can be individually disclosed or withheld. This is controlled at two levels:

* **At template level**: Issuers mark certain attributes as `alwaysDisclosed` — these are always shared
* **At presentation time**: Youth choose which remaining attributes to reveal

## Codes and Types

The **code** and **type** fields are how the ecosystem stays connected without partners needing direct relationships.

When creating a credential template, you provide a human-readable **`code`** (e.g. `course-completion`). The API uses this to generate a **Verifiable Credential Type (VCT)** — a full URI that uniquely identifies this credential across the ecosystem:

```
Issuer creates template with code: "course-completion"
  → API returns type: "https://didx.co.za/vct/didx/course-completion"
                                        ↓
Verifier creates presentation template
  → references type: "https://didx.co.za/vct/didx/course-completion"
```

Issuers and verifiers don't need a direct relationship — the shared VCT is the bridge.

<Note>
  Share the `type` URI from your credential template response with any verifying partner who needs to request credentials of that type.
</Note>

## Credential Format: SD-JWT-VC

All credentials use the **SD-JWT-VC** format (Selective Disclosure JSON Web Token — Verifiable Credential), an open standard enabling selective disclosure, cryptographic verification, and cross-wallet compatibility.

## Ecosystem Presets

YoID provides **ecosystem presets** — standardised credential structures that define common credential types across the YOMA network. Partners can:

* **Create a template from a preset** — use a pre-defined structure as-is for quick onboarding
* **Customise based on a preset** — start from a YoID preset and add or modify attributes to fit their specific programme

Presets ensure consistency across the ecosystem while giving partners the flexibility to capture what matters for their context.

## Async Credential Pipeline

Credentials can be issued before the youth has activated their wallet. The credential is held in a custodial state until the youth signs in — partners don't need to coordinate around wallet activation timing.

## Next Steps

<CardGroup cols={2}>
  <Card title="Start Integrating" icon="code" href="/api/introduction">
    Ready to build? Start with the API introduction
  </Card>

  <Card title="Issuer Workflow" icon="graduation-cap" href="/api/issuers/overview">
    See how learning and impact partners issue credentials
  </Card>
</CardGroup>