Skip to main content
Version: Next

Register Credentials for the Digital Credentials API

The Digital Credentials API (DC-API) lets verifiers request credentials through the operating system instead of through a QR code or deep link. When a website or app makes a DC-API request, the operating system shows the user the matching credentials from every registered wallet, and the user chooses which one to present.

For your wallet's credentials to appear in that selection, the wallet must first register them with the platform's native credential registry. This guide covers that registration step.

Prerequisites​

Registration builds on each platform's own credential APIs, and each platform has its own setup requirements. The SDK handles the registration calls, but your app must meet the platform requirements. Review the platform documentation before you start.

How registration works​

The SDK includes a default credential manager for each platform and passes it to the Core automatically at initialization. No setup is required, and the credential manager cannot be replaced from React Native.

Registration only happens when your app runs the CREDENTIAL_REGISTRY_SYNC task. A wallet that never runs the task never registers anything with the operating system.

Each sync is a full snapshot. The Core collects every eligible credential for the organization and passes the complete list to the credential manager, which replaces the wallet's previous registrations with the new list. Credentials that are no longer eligible, such as deleted or revoked credentials, are removed from the registry by the next sync.

Run the sync​

1. Run the task​

Run the CREDENTIAL_REGISTRY_SYNC task with the organization ID and the language currently selected in your app's UI.

await core.runTask(
  'CREDENTIAL_REGISTRY_SYNC',
  JSON.stringify({
    organisationId: organisationId,
    language: 'en', // Language currently selected in the UI
  }),
);

Both parameters are required:

ParameterDescription
organisationIdThe organization whose credentials are registered.
languageThe language used for credential names, issuer names, and claim labels shown in the operating system's credential selector.

On success, the task returns an empty JSON object ("{}").

note

The language value must exactly match the language code used in your credential schema translations. For example, en-US does not match translations stored as en. When no translation matches, the operating system shows fallback labels. See How credentials are displayed.

2. Run the sync again when credentials change​

Because each sync replaces the previous registrations, run it again whenever the set of eligible credentials changes. Typical triggers include:

  • A credential is issued to the wallet
  • A credential is deleted
  • A credential changes state, for example after a revocation check
  • The user changes the UI language
  • The user switches to a different organization
  • The app starts or returns to the foreground

When and how often to sync is up to your app.

note

On iOS, the first sync shows the user a system prompt to authorize the app. If the user declines, the sync fails. The user can authorize the app later in its page in Settings, but credentials are only registered at the next sync. Running the sync when the app starts or returns to the foreground makes sure this happens.

What gets registered​

Registration happens in two stages. The Core selects and maps the eligible credentials, then the platform's credential manager decides which of those to register with the operating system.

Core selection​

The Core includes a credential when all of the following are true:

  • It belongs to the specified organization.
  • The wallet holds it (holder role).
  • It is in the ACCEPTED state. Suspended and revoked credentials are not usable and are not registered.
  • It has not been deleted.
  • Its format is SD-JWT VC or ISO mdoc. Other formats are not eligible.

Batch credentials. A batch is included when it has at least one unconsumed batch item. The Core registers one entry per format type in the batch. A batch holding both an SD-JWT VC and an mdoc therefore produces two registrations, one per format, both using the batch's credential ID.

Claims. For each credential, the Core registers its claims with:

  • a path built from the claim's technical key, with the mdoc namespace as the first segment for mdoc credentials
  • a display name in the requested language
  • whether the claim is selectively disclosable

Metadata claims are not registered. Claims nested inside an array are not registered individually; the array claim itself is registered once.

Platform registration​

The default credential managers behave differently on each platform.

Android​

The Android credential manager registers all SD-JWT VC and mdoc credentials it receives, including their claims and display information. The operating system uses this information to match credentials against a verifier's request and to show them in the credential selector.

For mdoc credentials, only top-level data elements (namespace and element identifier) are registered. Claims nested below a data element are skipped. For SD-JWT VC credentials, all claim paths are registered.

iOS​

The iOS credential manager registers mdoc credentials only. SD-JWT VC credentials are skipped.

iOS supports the following mdoc document types:

  • eu.europa.ec.av.1
  • eu.europa.ec.eudi.pid.1
  • org.iso.23220.photoid.1
  • org.iso.23220.1.jp.mnc
  • org.iso.18013.5.1.mDL

Declare the document types your wallet provides in the app's entitlement. Only mdoc credentials with a declared, supported document type can be registered.

iOS registers each credential by its document type and credential ID. Claims and display information are not used; the operating system handles credential display itself.

How credentials are displayed​

This section applies to Android. iOS does not use the display information provided by the Core.

Shown in selectorSourceFallback
TitleCredential schema name translation for languageCredential schema name
SubtitleIssuer name translation for languageNone (no subtitle shown)
IconCredential schema logoApp icon
Claim labelClaim name translation for languagemdoc: element identifier. SD-JWT VC: claim path joined with /

The logo is only used when it is a PNG or JPEG data URL (data:image/png;base64,... or data:image/jpeg;base64,...). Any other format falls back to the app icon.

Errors and troubleshooting​

If any part of the sync fails, the task returns an error and the remaining credentials are not registered.

ErrorPlatformCause
Validation error: missing paramsBothorganisationId or language was not provided.
Synchronization error (BR_0516): IdentityDocumentProviderRegistrationStore unavailableiOSThe device runs an iOS version earlier than 26.
Synchronization error (BR_0516): device platform not supportediOSThe device does not support document providing.
Synchronization error (BR_0516): user did not authorize appiOSThe user declined the authorization prompt, or the app has no Identity Document Provider extension. The user can authorize the app later in its page in Settings.
Synchronization error (BR_0516)AndroidThe Android registry rejected the registration.

Interrupted syncs. if a sync fails partway, the registry may be left incomplete or empty until the next successful sync. Running the sync again restores the correct state.

Next steps​