Credential Definitions

A credential definition is an issuer template. It tells wallets what kind of credential you issue and which claim paths can appear in it. Definitions move in one direction:

Status	Allowed actions	Can issue?
`draft`	read, update, publish, archive	No
`published`	read, archive	Yes
`archived`	read	No

Published definitions are immutable. Create a new version when wallet-visible fields need to change.

Credential-definition lifecycle methods (createDraft, update, publish, archive, and lifecycle list filters) ship in @authbound/server 0.3.0 and later. Use create() when you want a published definition immediately, or the draft workflow when staging is intentional.

Dashboard builder

The dashboard builder starts from a template or custom definition, then walks through Details, Fields, Appearance, and Review. Check the wallet and API previews, save a draft while editing, and publish when ready. Issuance navigation requires enablement for your organization. A new organization may not have it enabled. Ask your Authbound contact if the Credentials section is absent.

Create and publish immediately

POST /v1/issuer/credential-definitions create sends explicit published intent. A published definition must include claims and pass publish-readiness validation.

await authbound.issuer.credentialDefinitions.create({
  credentialDefinitionId: "pension_credential_v1",
  vct: "urn:vc:authbound:pension:1.0",
  format: "dc+sd-jwt",
  title: "Pension Credential",
  aliases: ["pension"],
  claims: [
    { path: ["Person", "given_name"], mandatory: true, displayName: "Given Name" },
    { path: ["Person", "family_name"], mandatory: true, displayName: "Family Name" },
    { path: ["Pension", "startDate"], mandatory: true, displayName: "Start Date" },
  ],
  idempotencyKey: "credential-definition:pension:v1",
});

Direct REST callers send "lifecycleStatus": "published". If the field is omitted, the backend creates a draft.

Work in a draft

Use a draft when the definition is not ready for issuance.

const draft = await authbound.issuer.credentialDefinitions.createDraft({
  credentialDefinitionId: "pension_credential_v2",
  vct: "urn:vc:authbound:pension:2.0",
  format: "dc+sd-jwt",
  title: "Pension Credential v2",
  metadata: { owner: "benefits" },
  idempotencyKey: "credential-definition:pension:v2",
});

await authbound.issuer.credentialDefinitions.update(draft.credentialDefinitionId, {
  claims: [
    { path: ["Pension", "startDate"], mandatory: true, displayName: "Start Date" },
  ],
});

const published = await authbound.issuer.credentialDefinitions.publish(
  draft.credentialDefinitionId,
  {
    idempotencyKey: "credential-definition:pension:v2:publish",
  }
);

An unready publish returns credential_definition_not_publishable with bounded details.issues entries. Reusing a publish idempotency key for a different definition returns HTTP 409.

List definitions

GET /v1/issuer/credential-definitions

const drafts = await authbound.issuer.credentialDefinitions.list({
  lifecycleStatus: "draft",
});

REST callers use ?lifecycle_status=draft, published, or archived. Omitting the filter returns the active view, which can include owned drafts. Global definitions are visible only while active and published; archived results are project-owned.

Retrieve and update a draft

const definition = await authbound.issuer.credentialDefinitions.get(
  "pension_credential_v2"
);

await authbound.issuer.credentialDefinitions.update(definition.credentialDefinitionId, {
  title: "Updated Pension Credential",
  aliases: ["pension", "retirement-benefit"],
});

Update accepts drafts only. Published and archived definitions return HTTP 409 with published_credential_definition_immutable or archived_credential_definition_immutable. IDs from another project or environment return the same 404 response as an absent ID.

Archive a definition

POST /v1/issuer/credential-definitions/{credentialDefinitionId}/archive

await authbound.issuer.credentialDefinitions.archive(
  "pension_credential_v1"
);

Archiving removes a definition from new issuance resolution. Existing issuance records remain auditable.

Wallet-visible fields and management metadata

Wallet-visible fields include title, aliases, rendering, and claim display names. Definition metadata is authenticated management metadata; wallets do not discover it, and it is not embedded in issued credentials. Keep all these fields free of secrets and unnecessary personal data. Put user-specific data in issuance claims. Definition metadata accepts JSON values with runtime limits: eight levels, 1,024 total nodes, 128 entries per object or array, and 2,048 characters per string. Prototype-related keys are rejected. Authbound’s structural issuer metadata is never returned through the public metadata field.

Start here

Identity verification

Credential issuance

AI

Dashboard builder

Create and publish immediately

Work in a draft

List definitions

Retrieve and update a draft

Archive a definition

Wallet-visible fields and management metadata

​Dashboard builder

​Create and publish immediately

​Work in a draft

​List definitions

​Retrieve and update a draft

​Archive a definition

​Wallet-visible fields and management metadata

Dashboard builder

Create and publish immediately

Work in a draft

List definitions

Retrieve and update a draft

Archive a definition

Wallet-visible fields and management metadata