# Manage a credential

Understand, control, and maintain credentials users already have.

Use this pattern when users need to:

* see what credentials they hold
* understand validity, expiry, or revocation
* respond to changes that affect future service access

Credential management is a cross-service capability, typically delivered through a wallet product or platform. This pattern describes how services interact with that capability, rather than how the wallet itself is built or operated.

## Steps

{% @mermaid/diagram content="---
config:
theme: redux
layout: dagre
-------------

flowchart LR
A\["1. Access credentials<br>"] --> B\["2. View credentials<br>"]
B --> C\["3. View credential details and status<br>"]
C --> D\["4. Has anything changed?<br>"]
D -- No --> E\["5. Take action?"]
D -- Yes --> N\["Notify user about change<br>"]
N --> E
E -- No --> Z\["Done<br>"]
E -- Yes --> M\["Manage credential (optional)<br>"]
M --> Z

A@{ shape: rounded}
B@{ shape: rounded}
C@{ shape: rounded}
D@{ shape: diam}
E@{ shape: diam}
N@{ shape: rounded}
Z@{ shape: rounded}
M@{ shape: rounded}" %}

<details>

<summary><strong>Example user flow</strong></summary>

<figure><img src="https://content.gitbook.com/content/u8moxPbFWK9pTxPYNIyh/blobs/1qNXy67wHbJXKWXJoXZ3/Manage%20a%20credential.png" alt=""><figcaption></figcaption></figure>

</details>

### 1. Access credentials

The user accesses their credentials via a wallet, account area, or assisted channel.

It must be clear:

* who holds the credential (user or service custody)
* where the credential is stored (wallet, physical eg paper or card, document based eg. PDF, email)
* that they persist beyond a single service journey
* how to access the credential (mobile app, web app, 2FA, fallback solutions (phone call/ID check))

**User scenarios to consider:**

* [Authenticate](https://specs.govstack.global/service-patterns/2.-functional-patterns/authenticate) to match a user to a credential where needed&#x20;
* Users may hold credentials in multiple wallets or formats. Avoid assuming a single store.
* Support delegated access to a credential where lawful (parent, carer, user or organisation representative)

### 2. View credentials

The user sees a list of credentials they hold. The list communicates:

* The name of each credential. Use plain language that is easy to understand
* what each credential is for
* whether it can be reused for other services

### 3. Understand credential details and status

The user views details for a specific credential to decide whether it can be used. It must be clear:

* what the credential proves (plain language)
* who issued it
* current status:
* valid / usable
* expired
* revoked
* temporarily unavailable
* validity period or expiry date (if applicable)

Design guidance

* Translate status into meaning (“You can use this”, “You need to update this”)
* Explain consequences (“This will not be accepted after…”)
* Do not expose cryptographic, trust framework or protocol details

### 4. Be informed when something changes

The user is made aware when a credential changes in a way that affects use. Use the notification pattern.&#x20;

Triggers include

* expiry approaching or reached
* revocation or suspension
* replacement or update
* changes in rule that affect acceptance

Use the notification pattern.

**Design guidance**

* Notifications should explain:
  * what changed
  * what it means
  * what action (if any) is needed
  * Which other active services are affected
* Do not rely on users checking proactively
* Support non-digital notification routes where needed such as letters, email, SMS, or assisted calls

### 5. Take action on a credential (optional)

Where allowed, the user can manage a credential.

Possible actions

* remove or archive a credential
* replace or update a credential
* start renewal or reissue
* get help or use an assisted route
* recovery after device or wallet loss

Ask users for information where their confirmation or input is required.&#x20;

Design guidance

* Be explicit about what actions are allowed and why
* Clearly explain the impact of actions
* Avoid irreversible actions without warning

***

## Considerations

* **Ownership and reuse:** users often don’t realise they already have credentials that can be reused. Designs should make this clear consistently.
* **Status clarity:** when a credential is marked as “valid,” it should mean the user can use it immediately.
* **Cross-service relevance:** where credentials can affect access to more than one service, make this clear.
* **Non-digital equivalence:** paper and assisted versions of credentials must be accurately represented
* **Low connectivity:** ensure users can view key credential information when offline