How to Import and Store W3C Credentials with walt.id

TL;DR

Learn how to import and store self-signed W3C credentials into your walt.id wallet using the Wallet API, including preparing credentials in JWT format and associating them with DIDs.

What you'll learn

  • Prepare self-signed W3C credentials in JWT format for import
  • Use the Wallet API import endpoint to store credentials in a wallet
  • Associate imported credentials with specific DIDs
  • Handle import responses and error codes

This guide will walk you through the process of importing and storing self-signed W3C credentials into your walt.id wallet using the API. This is particularly useful for testing and development purposes.

Prerequisites

  • A walt.id wallet set up and running. If you haven't set up a wallet yet, you can follow the walt.id wallet setup guide.
  • A self-signed W3C credential in JWT format that you want to import into the wallet.
  • A did you want to associate the credential with.

Steps to Import and Store Credentials

1. Prepare Your Self-Signed Credential

Ensure you have a self-signed W3C credential in JWT format that:

  • Includes the necessary claims for your use case.
  • Is properly signed with the key you control.

Here is an example of a self-signed credential in JWT format:

{
  "iss": "did:example:123456789abcdefghi",
  "sub": "did:example:abcdefghi123456789",
  "vc": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1"
    ],
    "type": ["VerifiableCredential"],
    "credentialSubject": {
      "id": "did:example:abcdefghi123456789",
      "name": "John Doe"
    }
  },
  "iat": 1618884473,
  "exp": 1672531199,
  "jti": "urn:uuid:123e4567-e89b-12d3-a456-426614174000"
}

2. Use the API to Import the Credential

You can use the following API endpoint to import the self-signed credential into your walt.id wallet:

CURL

Endpoint:/wallet-api/wallet/{wallet_id}/credentials/import| API Reference

Example Request:

curl -X 'POST' \
  'https://wallet.test.waltid.cloud/wallet-api/wallet/{wallet_id}/credentials/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "jwt": "eyJraWQiOiJWeng3bDVmaDU2RjNQZjlhUjNERUNVNUJ3ZnJZNlpKZTA1YWlXWVd6YW44IiwiYWxnIjoiRWREU0EifQ.eyJpc3MiOiJkaWQ6a2V5Ono2TWtqb1JocTFqU05KZExpcnVTWHJGRnhhZ3FyenRaYVhIcUhHVVRLSmJjTnl3cCIsInN1YiI6ImRpZDprZXk6ejZNa2pvUmhxMWpTTkpkTGlydVNYckZGeGFncXJ6dFphWEhxSEdVVEtKYmNOeXdwIiwidmMiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy9leGFtcGxlcy92MSJdLCJpZCI6Imh0dHA6Ly9leGFtcGxlLmdvdi9jcmVkZW50aWFscy8zNzMyIiwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIlVuaXZlcnNpdHlEZWdyZWVDcmVkZW50aWFsIl0sImlzc3VlciI6eyJpZCI6ImRpZDp3ZWI6dmMudHJhbnNtdXRlLndvcmxkIn0sImlzc3VhbmNlRGF0ZSI6IjIwMjAtMDMtMTBUMDQ6MjQ6MTIuMTY0WiIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmV4YW1wbGU6ZWJmZWIxZjcxMmViYzZmMWMyNzZlMTJlYzIxIiwiZGVncmVlIjp7InR5cGUiOiJCYWNoZWxvckRlZ3JlZSIsIm5hbWUiOiJCYWNoZWxvciBvZiBTY2llbmNlIGFuZCBBcnRzIn19fX0.PureDss8Z-w3fyrraVEds0-qftaadS6i7JqF1zxjxAUpFY2qUNGNiiQUaQ5pACFVRmJv7bw1SQZqnkZgstDlAA",
  "associated_did": "did:jwk:eyJrdHkiOiJPS1AiLCJjcnYiOiJFZDI1NTE5Iiwia2lkIjoiaDRDcmJUYnc1NG8wTFMtLWtMTUUzSFZ4ZFpTczNHa0YyS1BUSEl0R0lqbyIsIngiOiJWZ0JFc0hwQmp3aE8waXZQWlpuS0MtY3dfeHNDYjZEbEhxUnd6SFRkN0RZIn0"
}'

Body Parameters:

  • associated_did: The DID to associate the credential with.
  • jwt: The self-signed W3C credential in JWT format.
  • Response Codes:
  • 201: Credential imported successfully.
  • 400: Invalid JWT or VC structure.
  • 401: Invalid authentication.
  • 409: Credential already exists.
Last updated on November 18, 2025
How to Present Digital Credentials (W3C, SD-JWT VC) via OID4VP using External Signatures with walt.idFeatures