> For the complete documentation index, see [llms.txt](https://opencred.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://opencred.gitbook.io/docs/readme.md).

# OpenCred Documentation

OpenCred is a local-first platform for issuing and verifying W3C Verifiable Credentials. It ships as a **Desktop Client** (Electron) for interactive use and a **Docker Image** (headless HTTP API + CLI) for cloud and CI/CD deployment. Issuer private keys never leave the issuer's environment — all signing happens locally on the issuer's machine or inside the issuer-operated container.

OpenCred is published by [NFH Trust Labs](https://github.com/nfh-trust-labs).

> **Open source.** OpenCred is open source under the [MIT licence](https://github.com/nfh-trust-labs/opencred/blob/main/LICENSE). Source code, issues, and release notes live at [github.com/nfh-trust-labs/opencred](https://github.com/nfh-trust-labs/opencred); contributions are welcome — see [CONTRIBUTING.md](https://github.com/nfh-trust-labs/opencred/blob/main/CONTRIBUTING.md). Desktop installers ship for macOS, Windows, and Linux. On first launch macOS shows a one-time approval prompt (see the [installation guide](/docs/desktop-app/installation.md#macos-first-launch)).
>
> **Support:** for bug reports, feature requests, or questions, [open an issue](https://github.com/nfh-trust-labs/opencred/issues). Security vulnerabilities go through [private reporting](https://github.com/nfh-trust-labs/opencred/security/advisories/new), not a public issue.

## Get OpenCred

|                                       | Where                                                          | How                                                                                            |
| ------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Desktop** (macOS / Windows / Linux) | <https://github.com/nfh-trust-labs/opencred-releases/releases> | Download the `.dmg` (Apple Silicon or Intel) / `.exe` / `.AppImage` / `.deb` for your platform |
| **Docker server**                     | `ghcr.io/nfh-trust-labs/opencred/opencred-server:latest`       | `docker pull ghcr.io/nfh-trust-labs/opencred/opencred-server:latest`                           |

Both are public — no authentication required. The source code is open source (MIT) at <https://github.com/nfh-trust-labs/opencred>; release binaries are mirrored to the [opencred-releases](https://github.com/nfh-trust-labs/opencred-releases/releases) download repo.

## Start Here

Pick the path that matches your role.

| You are...                                  | Start here                                                                                 |
| ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| New to verifiable credentials               | [Concepts](/docs/concepts/concepts.md) — what VCs, DIDs, and trust chains are              |
| Running a workshop or evaluating end-to-end | [Bootcamp Guide](/docs/bootcamp/bootcamp.md) — guided 3-hour path through the Docker image |
| Installing the desktop app                  | [Desktop User Guide](/docs/desktop-app/desktop.md)                                         |
| Deploying the Docker image                  | [Docker Operator Guide](/docs/docker-image/docker.md)                                      |
| **Verifying a credential someone gave you** | [Verifying credentials](#verifying-a-credential) (below)                                   |
| Reviewing OpenCred's security posture       | [Security Model](/docs/security/security.md)                                               |
| Contributing or building from source        | [Developer Guide](/docs/developer-guide/development.md)                                    |

## Verifying a credential

Anyone holding an OpenCred-issued credential has four supported ways to verify it. All four run the same `@opencred/verification` engine — pick the surface that matches your environment.

| Path                                              | Best for                                                  | Inputs accepted                                                                                                                                                                           |
| ------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Desktop app — Verify tab**                      | Casual / one-off verification by humans                   | Pasted JSON · drag-dropped `.json` / `.jsonld` · QR-code image upload (PNG/JPG) · `.pdf` upload · live camera QR scan · pasted compact tokens (vc-jwt, sd-jwt-vc, bare PixelPass QR data) |
| **Docker server — `POST /v1/credentials/verify`** | Programmatic / server-to-server / CI/CD                   | JSON body for text-shaped formats (auto-detected: JSON-LD VC, vc-jwt, sd-jwt-vc, PixelPass QR data) **or** raw PDF body with `Content-Type: application/pdf`                              |
| **`opencred verify` CLI**                         | One-shot verification from a shell, no HTTP server needed | File path or stdin. Auto-detects JSON-LD, vc-jwt, sd-jwt-vc, PixelPass QR data, or PDF. `--json` flag for scripted consumers. Ships inside the public Docker image.                       |
| **`@opencred/verification` library**              | Embedding verification inside another Node.js app         | Same formats as above, via `verifyCredential` and `verifyPdf`                                                                                                                             |

In every case the result has the same shape: a top-level `valid: true|false`, an enum `code` (`VALID`, `REVOKED`, `EXPIRED`, `INVALID`, `UNRESOLVABLE`, `CONTEXT_MISSING`), and a per-check breakdown — signature, expiry, key resolution, x5c chain (where applicable), revocation, schema, context.

**`did:key`-issued credentials verify fully offline.** `did:web` credentials need network access to fetch the issuer's DID document. DSC-backed credentials carrying an `x5c` chain need a CSCA trust store on disk — see [Trust chains](/docs/concepts/trust-chains.md) and [Docker → API reference → Verify](/docs/docker-image/api-reference.md#post-v1credentialsverify).

**PDF certificates.** OpenCred packages credentials as printable PDFs with a scannable QR embedded **and** a copy of the credential payload tucked into the PDF's info dictionary. Either path works: drop the PDF into the desktop Verify tab, POST it to `/v1/credentials/verify`, or pipe it into `opencred verify --input -`. Older PDFs issued before the info-dict embedding shipped (no payload in metadata) surface as a clear "scan the QR or extract the embedded JSON" message rather than a generic failure.

For full step-by-step, see [Desktop → Verifying credentials](/docs/desktop-app/verifying-credentials.md) or [Docker → API reference](/docs/docker-image/api-reference.md#post-v1credentialsverify).

## Documentation Sections

### Concepts

Background reading for anyone working with OpenCred.

* [Concepts overview](/docs/concepts/concepts.md)
* [Verifiable Credentials](/docs/concepts/verifiable-credentials.md) — what a VC is, payload structure, proof formats, status
* [DIDs](/docs/concepts/dids.md) — `did:key`, `did:jwk`, and `did:web`, and when to use each
* [Trust chains](/docs/concepts/trust-chains.md) — the three issuer types and how trust flows
* [Revocation](/docs/concepts/revocation.md) — how OpenCred handles status checks and DeDi

### Desktop Client

Interactive credential issuance and verification on macOS, Windows, and Linux.

* [Desktop overview](/docs/desktop-app/desktop.md)
* [Installation](/docs/desktop-app/installation.md)
* [Getting started](/docs/desktop-app/getting-started.md) — first launch and onboarding wizard
* [Key management](/docs/desktop-app/key-management.md) — DSC import, hardware tokens, OS cert store, generated keys
* [Issuing credentials](/docs/desktop-app/issuing-credentials.md) — single and batch issuance
* [Verifying credentials](/docs/desktop-app/verifying-credentials.md)
* [Settings and logging](/docs/desktop-app/settings-and-logging.md)

### Docker Image

Headless deployment for cloud, on-prem, and CI/CD pipelines. The Docker image runs in **your** infrastructure — no data is sent to OpenCred or NFH Trust Labs.

* [Docker overview](/docs/docker-image/docker.md)
* [Deployment](/docs/docker-image/deployment.md) — `docker run`, Compose, environment variables, volumes
* [API reference](/docs/docker-image/api-reference.md) — HTTP endpoints
* [CLI reference](/docs/docker-image/cli-reference.md) — `opencred` command-line tool
* [Cloud HSM](/docs/docker-image/cloud-hsm.md) — AWS KMS, Azure Key Vault, GCP Cloud KMS
* [Observability](/docs/docker-image/observability.md) — logging, health checks, metrics
* [OID4VCI](/docs/docker-image/oid4vci.md) — OpenID for Verifiable Credential Issuance (planned)

### Bootcamp

A guided, hands-on 3-hour path attendees follow at workshops or that you can use to evaluate the project end-to-end. Two parallel tracks: laptops only, or one shared cloud VM.

* [Bootcamp overview](/docs/bootcamp/bootcamp.md)
* [Local Docker track](/docs/bootcamp/local-docker.md) — every attendee runs the container on their own laptop
* [GCP VM track](/docs/bootcamp/gcp-vm.md) — one shared GCP VM, IAP-tunnelled SSH, optional Cloud KMS

### Security Model

How OpenCred handles keys, what it protects against, and where the guarantees are enforced.

* [Security overview](/docs/security/security.md)
* [Threat model](/docs/security/threat-model.md) — what we protect against and what we don't
* [Key handling](/docs/security/key-handling.md) — the never-touch-issuer-keys guarantee
* [Invariants](/docs/security/invariants.md) — the seven mandatory rules and where they're enforced

### Developer Guide

Contributing to OpenCred itself.

* [Developer overview](/docs/developer-guide/development.md)
* [Package layout](/docs/developer-guide/package-layout.md) — monorepo structure
* [Building](/docs/developer-guide/building.md) — pnpm, Turborepo, native addons
* [Testing](/docs/developer-guide/testing.md) — vitest, integration tests, coverage

## Reference Docs

Standalone reference documents for quick access:

* [Server API Reference](https://github.com/nfh-trust-labs/opencred/tree/new-opencred-dev/docs/api-reference.md) -- all HTTP endpoints with request/response schemas and curl examples
* [Deployment Guide](https://github.com/nfh-trust-labs/opencred/tree/new-opencred-dev/docs/deployment-guide.md) -- Docker, Compose, nginx reverse proxy, environment variables, production checklist
* [Credential Customization](https://github.com/nfh-trust-labs/opencred/tree/new-opencred-dev/docs/credential-customization.md) -- branding colors, logos, display names for packaged credentials
* [Architecture Overview](https://github.com/nfh-trust-labs/opencred/tree/new-opencred-dev/docs/architecture.md) -- monorepo structure, package responsibilities, key flows, security model

## Source of Truth

OpenCred is open source under the [MIT license](https://github.com/nfh-trust-labs/opencred/tree/new-opencred-dev/LICENSE/README.md). Source code, issues, and releases all live in this repository.

For end users:

* **Download a release**: <https://github.com/nfh-trust-labs/opencred-releases/releases>
* **Pull the Docker image**: `docker pull ghcr.io/nfh-trust-labs/opencred/opencred-server:latest`
* **Bug reports / feature requests**: <https://github.com/nfh-trust-labs/opencred/issues>

For contributors: product requirements live in [`docs/PRD.md`](https://github.com/nfh-trust-labs/opencred/tree/new-opencred-dev/docs/PRD.md), and the contribution workflow (branch model, commit conventions, DCO) in [`CONTRIBUTING.md`](https://github.com/nfh-trust-labs/opencred/tree/new-opencred-dev/CONTRIBUTING.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://opencred.gitbook.io/docs/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.