Creating your first credential config

A credential configuration is the template for everything you’ll issue: which format the credential takes on the wire, what claims it carries, which key signs it, and how it’s rendered as a PDF. This page walks through creating one end to end.

Prerequisites

Before you start you need:

• An active tenant (see Onboarding).
• Signing turned on (see Configuring a signer) — the recommended Cyfher-managed option sets this up for you, or connect your own backend — with at least one signing key under Keys.

The portal dashboard will surface both of these as next steps until they’re done.

Step 1 — Pick a preset (or start from scratch)

Navigate to Configurations in the portal sidebar and click New Configuration. You’ll land on a preset picker.

Presets are starting points filtered by category (Diploma, License, ID, Membership, Open Badge, etc.). They pre-fill the format, claims schema, certificate template, and category. You can edit anything afterwards. If none fit, choose Start from scratch.

Step 2 — Choose a format

Cyfher supports four credential formats. Pick based on what the verifier on the other end expects:

• SD-JWT VC (RFC 9901) — selective disclosure JWT. Sensible default for most use cases; let holders share only specific claims.
• W3C VC (VC-JWT) — W3C Verifiable Credentials Data Model 2.0 in JWT form. For verifiers that explicitly require W3C.
• mdoc (ISO 18013-5) — mobile document format. Required for mobile driver’s licences and government ID interop.
• Open Badge 3.0 — for educational badges, micro-credentials, and CLR (Comprehensive Learner Records).

You can change format later by creating a new config, but you cannot retroactively change the format of credentials already issued.

Step 3 — Attach a signing key

Pick a signing key from the dropdown. The dropdown is filtered to keys whose algorithm is valid for the chosen format (e.g. mdoc requires ES256; Open Badge supports EdDSA). Each key references the signer config that backs it.

Step 4 — Define the claims

The claims template is JSON describing the credential’s payload. Variables wrapped in {{ }} are substituted at issuance time from the recipient data. Example:

{
  "given_name": "{{given_name}}",
  "family_name": "{{family_name}}",
  "qualification": "Bachelor of Science",
  "awarded_at": "{{awarded_at}}"
}

The claims schema is a JSON Schema that Cyfher validates incoming claim data against before issuance. Strict by default — unknown fields are rejected. Both fields are pre-filled when you start from a preset.

For mdoc configs, the claims form adds a Namespace field instead — ISO 18013-5 groups data elements under a namespace, and every claim you define is issued into the one you enter here. It’s pre-filled with the standard org.iso.18013.5.1 namespace, which suits most documents. The Mobile Driving Licence preset (under the Identity category) starts you off with this pre-filled.

For external claim sources (webhooks that resolve claim data from your system of record at issuance time), see the Claims source tab on the config form.

Step 5 — Branding and PDF certificate (optional)

• Display name, description, logo, colors — show up in the wallet when the credential is offered and stored.
• Certificate template — Typst source that renders a PDF certificate. Cyfher renders entirely in-process (no browser, no Chromium). Template data is exposed via sys.inputs.data.*. Leave blank if you don’t need a PDF.

Reserved sys.inputs.data.* keys

If the config is linked to an achievement, Cyfher populates sys.inputs.data with a fixed set of platform-reserved keys before your own certificate_data is merged on top. Each key is only present when the underlying value is non-blank, so always read them with safe access and a default, e.g. sys.inputs.data.at("achievement_name", default: "").

Key	Meaning
achievement_name	The linked achievement’s name
achievement_type	Humanized achievement type label (e.g. “Diploma”, “Certificate”)
criteria_narrative	Free-text narrative from the achievement’s criteria
field_of_study	The achievement’s field of study
specialization	The achievement’s specialization within that field
credits	Credits available for the achievement, as a number
achievement_image	URL of the achievement’s image, if one is uploaded
recipient_name	The recipient’s name, from the recipient_name (or name) claim on the issuance request

The built-in default template (used when a linked achievement has no custom template) already renders these keys — see it for a worked example of safe access.

Step 6 — Save and activate

Click Save. The configuration is created in draft state. From the configurations list, click Activate on the row. Active configurations can be issued against; inactive ones cannot.

What’s next

Once active you have two paths to actually issue credentials:

• API issuance — the Distributions flow (distribution → batch → offers → commit → distribute) issues credentials programmatically. Even a single credential is a one-row batch. See Issuing a credential.
• Bulk distribution — for cohorts, upload a CSV. See Bulk distribution.