Configuration

Configuration#

The Verifiable Credentials feature is optional. It is disabled by default.

Note

If you are using Tutor, start with Quick Start for installation and setup. The quick start covers the tutor-credentials and tutor-contrib-badges plugins, feature flags, and the initial issuer setup flow.

Use this page for manual configuration, overrides, and detailed settings reference.

Conditional activation#

The verifiable_credentials app is always in INSTALLED_APPS, but its URL routes, signals, and system checks only activate when ENABLE_VERIFIABLE_CREDENTIALS is set to True. After changing this setting, restart the Credentials service for the change to take effect.

Learner Record MFE settings#

The Learner Record MFE uses environment variables configured in its .env file.

Note

In Tutor deployments, the Learner Record MFE is typically provided by the tutor-mfe plugin, and the Credentials service is provided by the tutor-credentials plugin. If you are using tutor-contrib-badges, it configures the required verifiable credentials feature flags automatically as part of the setup described in Quick Start.

ENABLE_VERIFIABLE_CREDENTIALS - enables the verifiable credentials UI routes.

SUPPORT_URL_VERIFIABLE_CREDENTIALS - footer support link on verifiable credentials pages.

Credentials service settings#

ENABLE_VERIFIABLE_CREDENTIALS (boolean) - main feature flag for the backend.

The feature introduces its own set of default settings, namespaced under the VERIFIABLE_CREDENTIALS setting:

VERIFIABLE_CREDENTIALS = {
    'DEFAULT_DATA_MODELS': [
        "credentials.apps.verifiable_credentials.composition.open_badges.OpenBadgesDataModel",
    ],
    "STATUS_LIST_LENGTH": 50000,
    "DEFAULT_ISSUER": {
        "NAME": "The University of the Digital Future",
        "KEY": '{"kty":"OKP","crv":"Ed25519","x":"IGUT8E_aRNzLqouWO4zdeZ6l4CEXsVmJDOpOQS69m7o","d":"vn8xgdO5Ki3zlvRNc2nUqcj50Ise1Vl1tlbs9DUL"}',
        "ID": "did:key:z6MkgdiV7pVPCapM8oUwfhxBwYZgh8dXkHkJykSAc4DHKD7X",
    },
}

This configuration overrides the corresponding built-in settings:

  1. Data models list narrowed down to a single specification.

  2. Status list length extended to 50K positions.

  3. Default issuer configured with concrete credentials.

Default settings#

All settings are defined under the VERIFIABLE_CREDENTIALS dictionary (see verifiable_credentials/settings.py for source).

Setting

Description / Default

DEFAULT_DATA_MODELS

Dotted paths to data model classes. At least one must be available, and every configured storage must reference an available data model.

Default: ["credentials.apps.verifiable_credentials.composition.verifiable_credentials.VerifiableCredentialsDataModel", "credentials.apps.verifiable_credentials.composition.open_badges.OpenBadgesDataModel"]

DEFAULT_STORAGES

Dotted paths to storage classes. At least one must be available.

Default: ["credentials.apps.verifiable_credentials.storages.learner_credential_wallet.LCWallet"]

STATUS_LIST_LENGTH

Per-issuer credential cap. Each issuer has a monotonically increasing status index capped by this value (unique_together constraint). Increase it or create additional issuers to issue more credentials. For details see the Status List 2021 specification.

Default: 10000 (16 KB)

STATUS_LIST_STORAGE

Storage class for the status list implementation.

Default: "credentials.apps.verifiable_credentials.storages.status_list.StatusList2021"

STATUS_LIST_DATA_MODEL

Data model class for the status list implementation.

Default: "credentials.apps.verifiable_credentials.composition.status_list.StatusListDataModel"

DEFAULT_ISSUANCE_REQUEST_SERIALIZER

Serializer for incoming issuance requests.

Default: "credentials.apps.verifiable_credentials.issuance.serializers.IssuanceLineSerializer"

DEFAULT_RENDERER

Renderer for outgoing verifiable credential responses.

Default: "credentials.apps.verifiable_credentials.issuance.renderers.JSONLDRenderer"

DEFAULT_ISSUER#

Issuer identity used during the first deployment data migration. Multiple IssuanceConfiguration records can exist in the database, but only the last enabled record is the active issuer for all verifiable credentials.

Important

The admin interface prevents disabling the last enabled configuration. Use remove_issuance_configuration to delete one entirely.

Key

Description / Default

NAME

Verbose issuer name embedded in each verifiable credential.

Default: "Default (system-wide)"

KEY

Private JWK used for signing. Use your own key or generate one with the generate_issuer_credentials command below.

Default: placeholder (must be replaced)

ID

Decentralized Identifier (DID) derived from the private key.

Default: placeholder (must be replaced)

Management commands#

All commands below run in the Credentials service.

generate_issuer_credentials#

Generates a new private key (JWK) and a decentralized identifier (DID) for an issuer.

./manage.py generate_issuer_credentials

Use the generated values as follows:

  • Set Issuer id to the generated did value.

  • Set Issuer key to the generated private_key value.

Warning

Treat private_key as a secret. Store it securely, do not commit it to version control, and do not expose it in logs or screenshots.

create_default_issuer#

Creates an Issuance Configuration from VERIFIABLE_CREDENTIALS[DEFAULT_ISSUER] settings at https://<your-credentials-host>/admin/verifiable_credentials/issuanceconfiguration/. A default configuration is created automatically during the first deployment via data migration. Use this command to re-create it if needed.

This command creates a new issuer configuration record from the current DEFAULT_ISSUER settings.

./manage.py create_default_issuer

remove_issuance_configuration#

Removes an issuer configuration by its DID. The admin interface only allows deactivation, not deletion.

This command permanently deletes the matching IssuanceConfiguration record.

./manage.py remove_issuance_configuration did:key:<UNIQUE_DID_KEY>

generate_status_list#

Generates a signed Status List 2021 credential for a given issuer. Useful for debugging revocation status or verifying the status list is correctly formed.

This command prints the signed Status List 2021 credential for the specified issuer.

./manage.py generate_status_list did:key:<UNIQUE_DID_KEY>

See also

Quick Start

Step-by-step setup including issuer credential generation (step 2) and configuration (step 3).

W3C Verifiable Credentials Data Model v1.1

The specification that defines the verifiable credential structure and lifecycle.

W3C Decentralized Identifiers (DIDs) v1.0

The specification for issuer and holder identifiers.

Status List 2021

The specification for credential revocation tracking.

Contents