Credential Expiration for Issuers

Credentials issued with Procivis One expire according to two configurable settings: technical expiration and administrative expiration (referred to as the administrative lifetime in the EUDI ARF). This page explains how to set both, and how they function together to control the lifetime of credentials.

Overview

	Technical expiration	Administrative expiration
Set in	Format config	Credential schema
Calculated from	Time of issuance	Time of credential creation

Technical expiration is set in configuration of each credential format and is calculated from the item's time of issuance. Administrative expiration is set during credential schema creation and is calculated from the time of credential creation — this sets how long you, as the issuing authority, endorse the claims in the credentials.

note

Administrative expiration starts counting down the moment you create the credential, not when it is issued. If there is significant time between creation and issuance the issued lifetime of the credential may be brief.

Expiration behavior differs between single credentials, batch parents, and batch items. This behavior is explained below. For more on the difference between single and batch credentials, see Single Credential and Batch Credential Issuance.

Setting expiration

Technical expiration

Set a technical expiration in a format's configuration:

format:
  SD-JWT:
    params:
      public:
        expirationSeconds: 63072000 # 2 years
  MDOC:
    params:
      public:
        expirationSeconds: 259200   # 72 hours

All credential formats have a default expirationSeconds. See Core Config Reference: Credential formats for details.

Administrative expiration

Set a credential's administrative expiration during credential schema creation using the expiration parameter. This parameter accepts integers as seconds.

Single credentials

Single credentials expire according to the administrative expiration. If no administrative expiration is set, the credential is valid forever, unless suspended or revoked.

exception

Credentials issued in mdoc format behave differently. See mdocs below.

Batch credentials

The administrative expiration applies directly to the batch parent and acts as an upper cap on the issued credential. Batch items are issued with the technical expiration unless that expiration goes past the administrative lifetime of the credential, in which case the technical expiration is reduced at the time of issuance to match the administrative expiration. Batch parents expire when one of two conditions has been met:

• The administrative expiration has been reached
• Both all batch items and the refresh token have expired

As long as the wallet has a valid refresh token and the batch parent has not expired, it can refresh issuance for a new batch of credentials.

If no administrative expiration is set, batch items are refreshable forever as long as the wallet has a valid refresh token. If the wallet fails to refresh before the token expires then the credentials will expire according to their technical expiration.

For setting refresh token expiration times, see Configuring OpenID4VC: Token and code expiration.

Manually stopping issuance with EXPIRING

In addition to the conditions above, you can manually put a batch credential on a path to expiration, at any time, regardless of whether an administrative expiration is set on the schema. For credentials with no administrative expiration, this is effectively the only way to wind down issuance for a credential, since without it a holder with a valid refresh token could otherwise refresh into new batches indefinitely.

EXPIRING can only be set on the batch parent, not on individual batch items.

Set a credential's state to EXPIRING:

PATCH /api/credential/v1/{credentialId}/state

{
  "state": "EXPIRING"
}

Once a credential is EXPIRING, the holder can no longer refresh and get a new batch. Batch items the holder already has are unaffected — they can continue presenting anything they have not used yet. When all remaining batch items expire, the credential moves to EXPIRED.

If you set the state back to ACCEPTED before that happens, the credential resumes normal batch behavior and the holder can refresh again.

note

This endpoint also accepts other lifecycle states. See Suspension and Revocation for details.

mdocs

For batch issuance, mdoc credentials follow the batch logic described above. For single-credential issuance, mdoc credentials also follow the batch logic (as though having a batch size of 1), rather than the single-credential logic.

Expired state

A credential can reach EXPIRED by hitting its administrative expiration, by exhausting its batch items with no valid refresh token, or after being set to EXPIRING. Once EXPIRED, the credential is no longer usable or refreshable.

Lifecycle check

Run the regular task LIFECYCLE_CHECK and the system updates all credential statuses. See Core Config Reference: Regular tasks for more information.