> For the complete documentation index, see [llms.txt](https://specs.govstack.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://specs.govstack.global/service-patterns/development/2.-functional-patterns/manage-a-credential.md).

# 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="/files/PqdYJOFQWDjhxrRiKGZX" 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](/service-patterns/development/2.-functional-patterns/authenticate.md) 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://specs.govstack.global/service-patterns/development/2.-functional-patterns/manage-a-credential.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.