Skip to content
ADR-0023Architecture decisionAcceptedversion 1.0.02 October 2026

Context ​

SPEC-WALLET-0001/WL7 says "there is no automatic renewal". The reason: if the wallet goes to the institution in the background, the institution learns how often the credential is used (SPEC-SCHEMA-0002 §2.1).

The EU ARF (Architecture and Reference Framework)The document set that describes roles, architecture, trust model and rules. Tamga ARF follows the structure of the EU ARF. 3.0 points the other way: re-issuance should require user action as little as possible (ISSU_42). With the single-use batch method, the wallet should request a new batch when it falls below a lower threshold (ISSU_45). Wallet and institution should support the re-issuance features of OpenID4VCI (OpenID for Verifiable Credential Issuance)The protocol an issuer uses to deliver a credential to a wallet. (ISSU_63).

Since 2026-09-29 Tamga institutions announce the thresholds in their metadata (credential_reuse_policy: batches of 10, when 2 copies remain, 7 days before expiry). Project management approved the same behaviour as the EU.

Constraint: silent renewal requires the institution to be able to sign again without asking the user.

  • Institution credentials (student, diploma): the institution reads the attributes again from its own authentic sourceThe system that actually owns the data in a credential, for example a university's student information system..
  • Identity credential (ADR-0011 K4) and contact credentials (ADR-0021 K3): the service does not keep the personal fields after issuance. Renewing them silently would require storing personal data. They are therefore out of scope.

Decision ​

K1 — When ​

The wallet renews an institution credential when one of these happens:

  • the number of unused copies falls to the institution's reissue_trigger_unused value (Tamga: 2),
  • the time left until the credential's expiry falls to reissue_trigger_lifetime_left (Tamga: 7 days).

Renewal happens only when all of these hold: the app is in the foreground, unlocked, and online. After the threshold is crossed a random delay (0–6 hours) is applied, so that the moment of renewal cannot be linked to the moment of a presentation.

K2 — How: the refresh token ​

  • On first issuance the institution returns a refresh_token in the token response (OpenID4VCI 1.0, RFC 6749 §6).
  • The token is bound to the DPoP (Demonstrating Proof of Possession)A way to bind an access token to a key, so a stolen token cannot be used without that key. key created for that credential (RFC 9449 §5). The wallet keeps this key for the life of the credential; each logical credential has its own key.
  • The wallet attestation (WUA (Wallet Unit Attestation)An attestation by the wallet provider about a wallet unit and the security of its keys; in the current EU texts it is split into WIA and key attestation.) is presented again with each renewal.
  • The token is single-use and is replaced by a new one at each use (rotation). Its lifetime never exceeds the credential's maximum validity.
  • A renewal returns a new batch (10 copies, new keys); old unused copies are deleted.

K3 — What the institution does ​

  • It reads the attributes again from the authentic source. If a field has changed, the wallet shows it to the user (ARF ISSU_59).
  • If the record no longer exists in the source (graduation, deregistration), the renewal is rejected and the token is revoked.
  • The validity of the new batch follows the rule of the type (student certificate ≤ 90 days). This way a student certificate refreshes itself for as long as the person remains a student.

K4 — Out of scope: identity and contact credentials, tickets ​

Identity and contact credentials receive no refresh token. They are renewed by user action (verifying the identity or the address again). Tickets are single-use and are not renewed. For these credentials the wallet warns, as today, when copies run low.

K5 — User setting ​

Settings has an "Automatically renew copies" option. It is on by default. When it is off, today's behaviour applies (warning

  • manual renewal).

K6 — Privacy balance ​

Residual risk: from the renewal frequency the institution can roughly infer how many new verifierThe party that checks a presented credential: signature, issuer in the trust list, status and policy. Also called relying party.s the credential was shown to (one request every 8 new verifiers). Mitigations:

  • the same copy for the same verifier (WL5); repeated presentations do not consume copies,
  • the random delay,
  • the renewal request does not contain which verifier the credential was presented to,
  • the user setting.

This is the same balance as the EU model. Project management accepted it.

Options considered ​

OptionResultWhy
No automatic renewal (WL7 as it is)rejectedConflicts with ARF ISSU_42/45; once copies run out the user cannot show the credential to a new verifier
Silent renewal with a new identity presentationrejectedEach renewal would mean an identity presentation = user consent and PIN; it cannot be silent
The identity service stores personal fields encryptedrejectedConflicts with ADR-0011 K4 and the data minimisation principle
Refresh token (bound to DPoP + WUA)acceptedThe standard OpenID4VCI path; the institution asks the authentic source again

Invariants ​

CodeRule
AR1Silent renewal happens only for credentials that have a refresh token, at the threshold announced by the institution, while the app is in the foreground and unlocked, and after a random delay.
AR2The refresh token is bound to the client-instance key of the issuance transaction (WIA cnf; ADR-0060 RT1), is single-use and changes at each use; a wallet attestation with the same instance key is verified at each renewal, the DPoP key may change (RT2).
AR3On renewal the institution reads the attributes again from the authentic source; if there is no record in the source, no credential is issued and the token is revoked.
AR4Services that do not store personal fields (identity, contact) issue no refresh token. The only exception is the ZK copy token (ADR-0044 ZC3: person fields are not kept on the server).

Consequences ​

  • SPEC-WALLET-0001/WL7 is reworded: "Renewal without user action happens only under the AR1–AR4 conditions."
  • SPEC-PROTO-0001: refresh_token at the token endpoint (the institution's issuerThe institution that signs and issues credentials: a university, a professional body, a public institution or a company.); grant_type=refresh_token (DPoP + WUA); token revocation.
  • apps/issuer (operator repository): refresh token store (as digests), re-reading from the authentic source.
  • wallet-core: per-credential DPoP key + refresh token storage; threshold check. Wallet: background renewal, setting, notification of changed fields.

Status ​

Accepted — 2026-09-29. With project management approval. DECISIONS: D-WALLET-1. Implementation queued.

2026-10-09: the ZK copy token exception was added to AR4 (ADR-0044, D-ZK-2).

2026-10-22: K2 and AR2 were changed by ADR-0060 — the binding moved from the DPoP key to the client-instance key (WIA cnf); the DPoP key may change at renewal (D-PROTO-4). The "DPoP + WUA bound" row in the options table is historical.

2026-11-16: AR4 narrowed by ADR-0089 (D-ID-17) — the identity credential is now silently renewed too: personal fields are still not stored; the wallet presents a copy of that record with all claims disclosed.