Verifiable Credentials can expire. It is useful to provide instructions on refreshing the credential for the times when expiration is imminent or has already occurred. The refresh can be performed manually or, with the prior consent of the credential holder, automatically.

This document specifies manual and automatic refresh mechanisms that Verifiable Credential issuers can utilize to enhance the experience when using their credentials.

Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-credentials@w3.org ( subscribe, archives).

Introduction

Verifiable Credentials can expire. It is useful to provide instructions on refreshing the credential for the times when expiration is imminent or has already occurred. The refresh can be performed manually or, with the prior consent of the credential holder, automatically.

A conforming refresh service implementation MUST provide at least one refresh protocol defined in Section [[[#refresh-protocol]]].

A conforming refresh client implementation MUST communicate with a [=refresh service implementation=] using at least one refresh protocol defined in Section [[[#refresh-protocol]]].

This document contains examples that contain JSON and JSON-LD content. Some of these examples contain characters that are invalid, such as inline comments (//) and the use of ellipsis (...) to denote information that adds little value to the example. Implementers are cautioned to remove this content if they desire to use the information as valid JSON or JSON-LD.

Terminology

Terminology used throughout this document is defined in the Terminology section of the [[[VC-DATA-MODEL-2.0]]] specification.

Refresh Data Model

This specification utilizes the Verifiable Credentials data model [[VC-DATA-MODEL]] and the Refreshing feature defined in that specification.

The `refreshService` Property

The refresh data model in this specification can be expressed directly on a [=verifiable credential=] via the refreshService property. The table below provides the structure of the refresh service description.

Property Description
type A REQUIRED string that MUST be set to `VerifiableCredentialInteractionService`.
serviceEndpoint A REQUIRED URL string, as defined by the Interaction URL section of the [[[VCALM]]] specification, that MUST be used to initiate a credential refresh.
validFrom An OPTIONAL [[XMLSCHEMA11-2]] datetime value that specifies the earliest moment in time that a refresh can be performed.
validUntil An OPTIONAL [[XMLSCHEMA11-2]] datetime value that specifies the latest moment in time that a refresh can be performed.

The example below demonstrates the use of the data model described in this section to specify a manual refresh service: 

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2",
    "https://w3id.org/vc-refresh-service/v2rc1"
  ],
  "id": "http://university.example/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://university.example/issuers/14",
  "validFrom": "2025-01-01T19:23:24Z",
  "validUntil": "2035-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "refreshService": {
    "type": "VerifiableCredentialInteractionService",
    "serviceEndpoint": "https://university.example/interactions/3732?iuv=1",
    "validFrom": "2034-09-01T19:23:24Z"
  }
}

The example below demonstrates the use of the data model described in this section to specify an automatic refresh service: 

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2",
    "https://w3id.org/vc-refresh-service/v2rc1"
  ],
  "id": "http://university.example/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://university.example/issuers/14",
  "validFrom": "2025-01-01T19:23:24Z",
  "validUntil": "2035-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  },
  "refreshService": {
    "type": "VerifiableCredentialInteractionService",
    "serviceEndpoint": "https://university.example/interactions/748?iuv=1",
    "validFrom": "2033-09-01T19:23:24Z",
    "validUntil": "2034-01-01T19:23:24Z"
  }
}

Performing an HTTP POST with an empty object on the `https://university.example/interactions/748?iuv=1` will initiate a presentation request using the [[[VCALM]]] specification.

The `RefreshCredential` Class

The refresh data model in this specification can also be expressed as a [=verifiable credential=] that can be used to refresh one or more other [=verifiable credentials=] via the RefreshCredential class. The table below provides the structure of the `RefreshCredential` class.

Property Description
type A set of strings that MUST include `VerifiableCredential` and `RefreshCredential`.
credentialSubject One or more objects that identify [=verifiable credentials=]. Identification mechanisms can include properties such as `id` or `digestMultibase`.
refreshService An object that MUST conform to the rules in Section [[[#the-refreshservice-property]]].

The example below demonstrates the use of the data model described in this section to specify a `RefreshCredential`: 

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2",
    "https://w3id.org/vc-refresh-service/v2rc1"
  ],
  "type": ["VerifiableCredential", "RefreshCredential"],
  "issuer": "https://university.example/issuers/14",
  "validFrom": "2025-01-01T19:23:24Z",
  "validUntil": "2035-01-01T19:23:24Z",
  "credentialSubject": [{
    "id": "https://university.example/credentials/123"
  }, {
    "digestMultibase": "uEiBdApsaWNlbnNpbmcgY29tbWl0bWVudC4KCklmIHlvdSB"
  }, {
    "digestMultibase": "uEiBbSBvbmUgcGVyCmxpbmUgYXMgZm9sbG93czoKCmBgYAo"
  }],
  "refreshService": {
    "type": "VerifiableCredentialInteractionService",
    "serviceEndpoint": "https://university.example/interactions/531?iuv=1",
    "validFrom": "2034-09-01T19:23:24Z"
  }
}

Refresh Protocol

This section details the protocols that can be used to refresh a credential. In general, all refresh protocols in this specification implement the following general pattern.

Manual Refresh

The manual protocol is used when an issuer uses a refresh prodedure that is non-automatable or requires an interactive exchange with the holder. The details of the protocol are defined in the Initiating Interactions section specified of the [[[VCALM]]] specification.

The example below demonstrates the requests and responses required to perform a manual refresh. The [=holder=]'s wallet initiates a refresh using the `serviceEndpoint` URL noting that it supports both manual and automated workflows. 

GET /interactions/3732?iuv=1 HTTP/1.1
Host: university.example
Accept: application/json

The refresh service responds with a [[[VCALM]]] exchange that will provide next steps. 

HTTP/1.1 200 OK
Date: Fri, 27 Sep 2025 12:03:57 GMT
Content-Type: application/json

{
  "protocols": {
    "vcapi": "https://university.example/workflows/123/exchanges/987"
  }
}

The [=holder=] starts the exchange by posting an empty object. 

POST /workflows/123/exchanges/987 HTTP/1.1
Host: university.example
Accept: application/json

{}

The [=issuer=] provides a `redirectUrl` which is a signal to the wallet software that the rest of the flow needs to be performed in a web browser. 

HTTP/1.1 200 OK
Date: Fri, 27 Sep 2025 12:03:58 GMT
Content-Type: application/json

{
  "redirectUrl": "https://university.example/get-your-degree/3829"
}

At this point, the [=holder=] is redirected to the provided website URL (`https://university.example/get-your-degree/3829`) and interacts with the website to get an updated degree as a [=verifiable credential=].

Automatic Refresh

The automatic refresh protocol is used when an issuer uses a refresh procedure that can be automated with the holder's software. The details of the protocol are defined in the Initiating Interactions section specified of the [[[VCALM]]] specification.

The example below demonstrates the requests and responses required to perform an automatic refresh. The [=holder=]'s wallet initiates a refresh using the `serviceEndpoint` URL noting that it supports both manual and automated workflows. 

GET /interactions/748?iuv=1 HTTP/1.1
Host: university.example
Accept: application/json

The refresh service responds with a [[[VCALM]]] exchange that will provide next steps. 

HTTP/1.1 200 OK
Date: Fri, 27 Sep 2025 12:03:57 GMT
Content-Type: application/json

{
  "protocols": {
    "vcapi": "https://university.example/workflows/748/exchanges/987"
  }
}

The [=holder=] starts the exchange by posting an empty object. 

POST /workflows/748/exchanges/987 HTTP/1.1
Host: university.example
Accept: application/json

{}

The refresh service responds with an automatic refresh request: 

HTTP/1.1 200 OK
Date: Fri, 27 Sep 2025 12:03:58 GMT
Content-Type: application/json

{
  "verifiablePresentationRequest": {
    "query": [{
        "type": "DIDAuthentication",
        "acceptedMethods": [{"method": "example"}],
        "acceptedCryptosuites": [{"cryptosuite": "ecdsa-rdfc-2019"}]
        }, {
        "type": "QueryByExample",
        "credentialQuery": {
          "reason": "We need to see your existing University Degree credential.",
          "example": {
            "@context": [
              "https://www.w3.org/ns/credentials/v2",
              "https://www.w3.org/ns/credentials/examples/v2"
            ],
            "type": "UniversityDegreeCredential"
          }
        }
      }],
      "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
      "domain": "university.example"
    }
  }
}

The [=holder=]'s software then responds with the appropriate credential: 

POST /workflows/748/exchanges/987 HTTP/1.1
Host: university.example
Content-Type: application/json
Accept: application/json, */*
Accept-Encoding: gzip, deflate

{
  "verifiablePresentation": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://www.w3.org/ns/credentials/examples/v2",
      "https://w3id.org/vc-refresh-service/v2rc1"
    ],
    "type": ["VerifiablePresentation"],
    "holder": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "verifiableCredential": [{
      "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://www.w3.org/ns/credentials/examples/v2",
        "https://w3id.org/vc-refresh-service/v2rc1"
      ],
      "id": "http://university.example/credentials/3732",
      "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
      ],
      "issuer": "https://university.example/issuers/14",
      "validFrom": "2024-01-01T19:23:24Z",
      "validUntil": "2034-01-01T19:23:24Z",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "degree": {
          "type": "BachelorDegree",
          "name": "Bachelor of Science and Arts"
        }
      },
      "refreshService": {
        "type": "VerifiableCredentialInteractionService",
        "serviceEndpoint": "https://university.example/interactions/92838?iuv=1",
        "validFrom": "2024-09-01T19:23:24Z",
        "validUntil": "2034-09-01T19:23:24Z"
      }
      "proof": {
        "type": "DataIntegrityProof",
        "cryptosuite": "ecdsa-rdfc-2019",
        "created": "2025-01-05T17:59:45Z",
        "verificationMethod": "https://university.example/issuers/14#key-1",
        "proofPurpose": "assertionMethod",
        "proofValue": "z2aArNcQKX9aqYK7GRZmV7c9xfGuwB5YAXhkYY9DTvLdTCQEsXaNpz1G
                      ZL9XDXdFQGT27WB68e2Y3wo9k75rka8oo"
      }
    }],
    "proof": {
      "type": "DataIntegrityProof",
      "cryptosuite": "ecdsa-rdfc-2019",
      "created": "2034-06-15T16:37:12Z",
      "verificationMethod": "did:example:76e12ec712ebc6f1c221ebfeb1f#key-1",
      "proofPurpose": "authentication",
      "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
      "domain": "university.example",
      "proofValue": "z4aU6NSpnCvnjJqzAPw3cqJ1LKoWimEWxKz7StJYzwaZE2a3QAuK8vcq
                    umwr6uabr7RshvjH1yTv1fTuhPUii1fN"
    }
  }
}
      
HTTP/1.1 200 OK
Date: Fri, 27 Sep 2025 12:03:59 GMT
Content-Type: application/json

{
  "verifiablePresentation": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://www.w3.org/ns/credentials/examples/v2",
      "https://w3id.org/vc-refresh-service/v2rc1"
    ],
    "type": ["VerifiablePresentation"],
    "verifiableCredential": [{
      "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://www.w3.org/ns/credentials/examples/v2",
        "https://w3id.org/vc-refresh-service/v2rc1"
      ],
      "id": "http://university.example/credentials/3732",
      "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
      ],
      "issuer": "https://university.example/issuers/14",
      "validFrom": "2024-01-01T19:23:24Z",
      "validUntil": "2044-06-14T18:37:12Z",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "degree": {
          "type": "BachelorDegree",
          "name": "Bachelor of Science and Arts"
        }
      },
      "refreshService": {
        "type": "VerifiableCredentialInteractionService",
        "serviceEndpoint": "https://university.example/interactions/892349?iuv=1",
        "validFrom": "2044-06-01T19:23:24Z"
      },
      "proof": {
        "type": "DataIntegrityProof",
        "cryptosuite": "ecdsa-rdfc-2019",
        "created": "2034-06-14T18:37:12Z",
        "verificationMethod": "https://university.example/issuers/14#key-1",
        "proofPurpose": "assertionMethod",
        "proofValue": "z2aArNcQKX9aqYK7GRZmV7c9xfGuwB5YAXhkYY9DTvLdTCQEsXaNpz1G
                      ZL9XDXdFQGT27WB68e2Y3wo9k75rka8oo"
      }
    }]
  }
}