Generic Issuer Service

https://github.com/swiyu-admin-ch/swiyu-issuer
Admin
This software is a web server implementing technical standards for the swiyu Trust Infrastructure...
Tokens:28,275
Snippets:217
Trust Score:8.4
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Start Application Locally

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Run this command to start the application locally with the 'local' profile. This will also start a PostgreSQL database via Docker.

```shell
./mvnw -f issuer-application spring-boot:run -Dspring-boot.run.profiles=local
```

--------------------------------

### Example proof_types_supported configuration

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

This snippet shows an example of how to configure the 'proof_types_supported' field, including nested options for proof signing algorithms and key attestations.

```json
"proof_types_supported": {
        "jwt": {
          "proof_signing_alg_values_supported": [
            "ES256"
          ],
          "key_attestations_required": {
            "key_storage": ["iso_18045_high"]
          }
        }
      }
```

--------------------------------

### Final Release Version Example

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Illustrates the transition from a Release Candidate to a final, official release by removing the prerelease suffix.

```text
1.4.0-rc.1, 1.4.0-rc.2 → 1.4.0 (final release)
```

--------------------------------

### Release Candidate Versioning Example

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Shows the format for Release Candidate (RC) versions, indicating a prerelease build intended for testing before the final release.

```text
x.y.z-rc.N (e.g., 1.4.0-rc.1, 1.4.0-rc.2)
```

--------------------------------

### Status List Creation Response

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Example response after successfully creating a status list, providing its ID, registry URL, and configuration details.

```json
{
    "id": "36f98a79-4be7-4978-bc46-071d8e40343a",
    "statusRegistryUrl": "your new $STATUS_REGISTRY_URL",
    "type": "TOKEN_STATUS_LIST",
    "maxListEntries": 100000,
    "remainingListEntries": 100000,
    "version": "1.0",
    "config": {
        "bits": 2
    }
}
```

--------------------------------

### Credential Offer Status Response

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Example response indicating the status of a credential offer, such as 'OFFERED'.

```json
{
    "status": "OFFERED"
}
```

--------------------------------

### Derived Image for SunPKCS11 HSM Integration

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/migration-guides/guide-3.1.x-to-3.2.x.md

This Dockerfile example demonstrates how to create a derived image for SunPKCS11 integration. It collects vendor and transitive native libraries from a Debian base image and layers them onto the Swiyu Issuer image, including the PKCS#11 configuration file.

```dockerfile
# Stage 1: collect vendor + transitive native libs from Debian packages
FROM debian:13-slim AS hsm-libs
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        libssl3 libgssapi-krb5-2 libkrb5-3 && \
    rm -rf /var/lib/apt/lists/*
# Vendor PKCS#11 .so brought in from your artifact store
COPY vendor/libCryptoki2_64.so /vendor/
# Stage 2: layer onto the hardened issuer image
FROM ghcr.io/swiyu-admin-ch/swiyu-issuer:3.0.0
USER 0
COPY --from=hsm-libs /usr/lib/x86_64-linux-gnu/libssl.so.3            /app/lib-native/
COPY --from=hsm-libs /usr/lib/x86_64-linux-gnu/libcrypto.so.3         /app/lib-native/
COPY --from=hsm-libs /usr/lib/x86_64-linux-gnu/libgssapi_krb5.so.2    /app/lib-native/
COPY --from=hsm-libs /usr/lib/x86_64-linux-gnu/libkrb5.so.3           /app/lib-native/
COPY --from=hsm-libs /vendor/libCryptoki2_64.so                       /app/lib-native/
COPY pkcs11.cfg                                                       /app/hsm/pkcs11.cfg
USER nonroot

```

--------------------------------

### Issuer and Token Endpoint Configuration

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Example of a metadata JSON file using the external-url template value for issuer and token endpoint.

```json
{
  "issuer": "${external-url}",
  "token_endpoint": "${external-url}/oid4vci/token"
}
```

--------------------------------

### Get Nonce

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Retrieves a nonce value required for creating a proof for a credential.

```APIDOC
## POST /oid4vci/api/nonce

### Description
Requests a nonce value from the issuer, which is necessary for generating a proof for a credential.

### Method
POST

### Endpoint
/oid4vci/api/nonce

### Parameters
No parameters are required for this request.

### Request Example
```bash
curl -X 'POST' 'http://localhost:8080/oid4vci/api/nonce' -H 'accept: application/json'
```

### Response
#### Success Response (200)
- **c_nonce** (string) - The generated nonce value.

#### Response Example
```json
{
    "c_nonce": "c9c737f3-f37b-4331-a23c-313dc821fac5::2025-08-07T16:30:19.021045078Z"
}
```
```

--------------------------------

### Get OpenID Connect Configuration

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

The wallet fetches the OpenID Connect metadata from the Issuer to determine how to obtain an access token. This is a standard OIDC discovery endpoint.

```bash
curl -X 'GET' 'http://localhost:8080/.well-known/openid-configuration' -H 'accept: application/json'
```

--------------------------------

### Bake Vendor JARs into Custom Image Layer

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/migration-guides/guide-3.1.x-to-3.2.x.md

For v3.0.0, runtime bootclasspath expansion is removed. Vendor JARs previously mounted via /lib must now be baked into a derived Docker image. This example shows how to copy a JCE provider JAR and configure the entrypoint.

```dockerfile
FROM ghcr.io/swiyu-admin-ch/swiyu-issuer:3.0.0
USER 0
COPY my-jce-provider.jar /app/lib-ext/my-jce-provider.jar
USER nonroot
ENTRYPOINT ["java", \
    "-Duser.timezone=Europe/Zurich", \
    "-Dspring.config.location=classpath:bootstrap.yml,classpath:application.yml,optional:file:/vault/secrets/database-credentials.yml", \
    "-Dfile.encoding=UTF-8", \
    "-Xbootclasspath/a:/app/lib-ext/my-jce-provider.jar", \
    "-jar", "/app/app.jar"]
```

--------------------------------

### Get Credential Offer Status

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Retrieves the current status of a previously created credential offer using its management ID.

```bash
curl -X 'GET' 'http://localhost:8080/management/api/credentials/$MANAGEMENT_ID/status' -H 'accept: application/json'
```

--------------------------------

### Credential Supported Metadata Example

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

This JSON object represents the metadata for a supported credential configuration. It includes identifiers, credential subject data, validity periods, status list URIs, and the integrity hash for the VCT.

```json
{
    "metadata_credential_supported_id": [
        "myIssuerMetadataCredentialSupportedId"
    ],
    "credential_subject_data": {
        "lastName": "Example",
        "firstName": "Edward"
    },
    "offer_validity_seconds": 86400,
    "credential_valid_until": "2030-01-01T19:23:24Z",
    "credential_valid_from": "2010-01-01T18:23:24Z",
    "status_lists": [
        "https://example-status-registry-uri/api/v1/statuslist/05d2e09f-21dc-4699-878f-89a8a2222c67.jwt"
    ],
    "credential_metadata": {
        "vct#integrity": "sha256-JXU3403niPeAUi8FN0IX6wfXafrgusykHC1LpKMOO94="
    }
}
```

--------------------------------

### Get Nonce for Proof Creation

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

This cURL command requests a nonce from the issuer, which is necessary for creating a verifiable proof for credential requests. Store the `c_nonce` for the next step.

```bash
curl -X 'POST' 'http://localhost:8080/oid4vci/api/nonce' -H 'accept: application/json'
```

--------------------------------

### Display Name Templating with Environment Variables

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Example of using a Spring environment variable 'stage' to prefix a display name in a metadata JSON file. The environment variable APPLICATION_TEMPLATEREPLACEMENT_STAGE must be set to provide the prefix.

```json
{
  "display": [
    {
      "name": "${stage}MyCredential",
...
```

--------------------------------

### Get credential offer status

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Retrieves the current status of a previously created credential offer using its management ID.

```APIDOC
## GET /management/api/credentials/$MANAGEMENT_ID/status

### Description
Fetches the status of a specific credential offer using its unique management ID. This is useful for tracking the progress of an offer after it has been generated.

### Method
GET

### Endpoint
`/management/api/credentials/$MANAGEMENT_ID/status`

### Parameters
#### Path Parameters
- **$MANAGEMENT_ID** (string) - Required - The management ID of the credential offer whose status is to be retrieved.

### Response
#### Success Response (200)
- **status** (string) - The current status of the credential offer (e.g., "OFFERED").

### Response Example
```json
{
    "status": "OFFERED"
}
```
```

--------------------------------

### SD-JWT Disclosure Handling Example

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/migration-guides/guide-2.4.x-3.0.0.md

Illustrates the JSON structure for SD-JWT disclosures with recursiveDisclosureEnabled set to false (default). Arrays are emitted with digests, and objects are flattened.

```json
{
    "_sd": [
        "..."
    ],
    "languages": [
        {
            "...": "some digest"
        }
    ]
}
```

--------------------------------

### Get Access Token

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Obtain a Bearer Token using a pre-authorized code from an offer deep link. The request body must be URL-encoded.

```APIDOC
## POST /oid4vci/api/token

### Description
Acquires an access token for credential issuance using a pre-authorized code.

### Method
POST

### Endpoint
/oid4vci/api/token

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be set to `urn:ietf:params:oauth:grant-type:pre-authorized_code`.
- **pre-authorized_code** (string) - Required - The pre-authorized code extracted from the offer deep link.

### Request Example
```bash
curl -X 'POST' \
  'http://localhost:8080/oid4vci/api/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code&pre-authorized_code=THIS_IS_THE_PRE_AUTHORIZED_CODE_FROM_THE_OFFER_DEEPLINK'
```

### Response
#### Success Response (200)
- **access_token** (string) - The obtained access token.
- **expires_in** (integer) - The token's expiration time in seconds.
- **token_type** (string) - The type of token, typically "BEARER".

#### Response Example
```json
{
    "access_token": "your $ACCESS_TOKEN",
    "expires_in": 600,
    "token_type": "BEARER"
}
```
```

--------------------------------

### Get Access Token for Credential Offer

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Use this cURL command to obtain an access token from the issuer by providing the pre-authorized code obtained from an offer deep link. The `grant_type` must be set to `urn:ietf:params:oauth:grant-type:pre-authorized_code`.

```bash
curl -X 'POST' \
  'http://localhost:8080/oid4vci/api/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code&pre-authorized_code=THIS_IS_THE_PRE_AUTHORIZED_CODE_FROM_THE_OFFER_DEEPLINK'
```

--------------------------------

### Get Credential Issuer Metadata

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

The wallet fetches the Issuer metadata to discover supported credential configurations, including proof types, cryptographic binding methods, and available claims. This endpoint is specific to OID4VCI.

```bash
curl -X 'GET' 'http://localhost:8080/oid4vci/.well-known/openid-credential-issuer' -H 'accept: application/json'
```

--------------------------------

### Setting up Native Libraries for HSM

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/migration-guides/guide-3.1.x-to-3.2.x.md

Configure the `ENTRYPOINT` to include the path to native libraries and set the `HSM_CONFIG_PATH` environment variable. Ensure the PKCS#11 configuration file points to the correct library path.

```dockerfile
ENTRYPOINT ["java", \
    "-Duser.timezone=Europe/Zurich", \
    "-Dspring.config.location=classpath:bootstrap.yml,classpath:application.yml,optional:file:/vault/secrets/database-credentials.yml", \
    "-Dfile.encoding=UTF-8", \
    "-jar", "/app/app.jar"]

```

--------------------------------

### Update Credential Offer Status

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/deferred.md

Allows the business issuer to update the status of a credential offer, for example, to 'READY'.

```APIDOC
## PATCH /management/api/credentials/{managementId}/status

### Description
Updates the status of a credential offer managed by the business issuer. This can be used to set the status to 'READY' or other defined states.

### Method
PATCH

### Endpoint
/management/api/credentials/{managementId}/status

### Parameters
#### Path Parameters
- **managementId** (string) - Required - The unique identifier for the credential offer to be updated.

#### Query Parameters
- **credentialStatus** (string) - Required - The desired status for the credential offer (e.g., 'READY').

### Response
#### Success Response (200)
- **id** (string) - The identifier of the updated credential offer.
- **status** (string) - The new status of the credential offer.

#### Response Example
```json
{
    "id": "$MANAGEMENT_ID",
    "status": "READY"
}
```
```

--------------------------------

### Get Deferred Credential

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/deferred.md

The wallet can fetch the deferred credential from the issuer. This endpoint is used when a credential cannot be issued immediately.

```APIDOC
## GET /.well-known/openid-configuration

### Description
Fetches the OpenID Connect metadata from the Issuer, which includes information on how to obtain an access token.

### Method
GET

### Endpoint
`http://localhost:8080/.well-known/openid-configuration`

### Response
#### Success Response (200)
- **issuer** (string) - The base URL of the issuer.
- **token_endpoint** (string) - The URL for obtaining an access token.

### Response Example
```json
{
    "issuer": "http://localhost:8080",
    "token_endpoint": "http://localhost:8080/oid4vci/api/token"
}
```

## GET /.well-known/openid-credential-issuer

### Description
Fetches the Issuer metadata, detailing supported credential configurations, proof types, cryptographic binding methods, and available claims.

### Method
GET

### Endpoint
`http://localhost:8080/oid4vci/.well-known/openid-credential-issuer`

### Response
#### Success Response (200)
- **credential_issuer** (string) - The URL of the credential issuer.
- **credential_response_encryption** (object) - Encryption details for credential responses.
  - **encryption_required** (boolean) - Indicates if encryption is required.
  - **alg_values_supported** (array) - Supported algorithms for key agreement.
  - **enc_values_supported** (array) - Supported content encryption algorithms.
- **display** (array) - Information for displaying the issuer to the user.
  - **name** (string) - The name of the issuer.
  - **locale** (string) - The locale for the display information.
  - **logo** (object) - Information about the issuer's logo.
    - **uri** (string) - The URI of the logo.
- **credential_configurations_supported** (object) - Supported credential configurations.
  - **[credential_id]** (object) - Details for a specific credential configuration.
    - **format** (string) - The format of the credential (e.g., 'dc+sd-jwt').
    - **credential_signing_alg_values_supported** (array) - Supported signing algorithms for credentials.
    - **cryptographic_binding_methods_supported** (array) - Supported cryptographic binding methods.
    - **proof_types_supported** (object) - Supported proof types.
      - **[proof_type]** (object) - Details for a specific proof type.
        - **proof_signing_alg_values_supported** (array) - Supported signing algorithms for proofs.
    - **vct** (string) - The Verifiable Credential Type identifier.
    - **claims** (object) - Supported claims for the credential.
      - **[claim_name]** (object) - Details for a specific claim.
        - **mandatory** (boolean) - Whether the claim is mandatory.
        - **value_type** (string) - The data type of the claim.
        - **display** (array) - Display information for the claim.
          - **locale** (string) - The locale for the display information.
          - **name** (string) - The name of the claim.
- **version** (string) - The version of the issuer metadata specification.
- **deferred_credential_endpoint** (string) - The endpoint for deferred credential issuance.
- **credential_endpoint** (string) - The endpoint for immediate credential issuance.

### Response Example
```json
{
    "credential_issuer": "http://localhost:8080",
    "credential_response_encryption": {
        "encryption_required": false,
        "alg_values_supported": [
            "ECDH-ES"
        ],
        "enc_values_supported": [
            "A128GCM"
        ]
    },
    "display": [
        {
            "name": "Mein Test Aussteller",
            "locale": "de-CH",
            "logo": {
                "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAIAAADYYG7QAAABD0lEQVR4nOyYsUrEQBRFVQYRYYUtZi0UC0vFUrBeYW1sF2E/wU623P8RkTSCf7FFipDaIkxhmkyapBgCYivz5sKAmynuaS9vOPDgcRlVXl/spcTB2AJ/oRCCQggKIVT8pJ4pfeqNnKmG1u5aaLpc6ecXb2Q26/Yji3s2uZVRCEEhBIUQFEKIl1rp2XS5Ckwe395J0WS+ODw7l1JX1zZ7ldJ9qVMfXd1cvn8GhKLpy+Lr6VFKk1sZhRAUQlAIIR5GZyqzWQcmJ/PFyf2DN2qyty7fSoODbWKEhtaGe/HvLRaEunzLTv1vUAhBIQSFEPGfDa7+7svCG4VvcRixwo5FciujEIJCCAohkhP6CQAA///lDD1tMy8HCAAAAABJRU5ErkJggg=="
            }
        },
        {
            "name": "My test issuer",
            "locale": "en-US",
            "logo": {
                "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAIAAADYYG7QAAABD0lEQVR4nOyYsUrEQBRFVQYRYYUtZi0UC0vFUrBeYW1sF2E/wU623P8RkTSCf7FFipDaIkxhmkyapBgCYivz5sKAmynuaS9vOPDgcRlVXl/spcTB2AJ/oRCCQggKIVT8pJ4pfeqNnKmG1u5aaLpc6ecXb2Q26/Yji3s2uZVRCEEhBIUQFEKIl1rp2XS5Ckwe395J0WS+ODw7l1JX1zZ7ldJ9qVMfXd1cvn8GhKLpy+Lr6VFKk1sZhRAUQlAIIR5GZyqzWQcmJ/PFyf2DN2qyty7fSoODbWKEhtaGe/HvLRaEunzLTv1vUAhBIQSFEPGfDa7+7svCG4VvcRixwo5FciujEIJCCAohkhP6CQAA///lDD1tMy8HCAAAAABJRU5ErkJggg=="
            }
        }
    ],
    "credential_configurations_supported": {
        "university_example_sd_jwt": {
            "format": "dc+sd-jwt",
            "credential_signing_alg_values_supported": [
                "ES256"
            ],
            "cryptographic_binding_methods_supported": [
                "jwk"
            ],
            "proof_types_supported": {
                "jwt": {
                    "proof_signing_alg_values_supported": [
                        "ES256"
                    ]
                }
            },
            "vct": "http://localhost:8080/vct/my-vct-v01",
            "claims": {
                "type": {
                    "mandatory": true,
                    "value_type": "string",
                    "display": [
                        {
                            "locale": "de-CH",
                            "name": "Abschluss Typ"
                        }
                    ]
                },
                "name": {
                    "mandatory": true,
                    "value_type": "string",
                    "display": [
                        {
                            "locale": "de-CH",
                            "name": "Diplomtitle"
                        }
                    ]
                },
                "average_grade": {
                    "mandatory": false,
                    "value_type": "number",
                    "display": [
                        {
                            "locale": "de-CH",
                            "name": "Notendurchschnitt"
                        }
                    ]
                }
            }
        }
    },
    "version": "1.0",
    "deferred_credential_endpoint": "http://localhost:8080/oid4vci/api/deferred_credential",
    "credential_endpoint": "http://localhost:8080/oid4vci/api/credential"
}
```

## POST /oid4vci/api/deferred_credential

### Description
This endpoint is used by the wallet to request a deferred credential from the issuer. The request typically includes an authorization code or other necessary identifiers obtained from a previous step.

### Method
POST

### Endpoint
`http://localhost:8080/oid4vci/api/deferred_credential`

### Request Body
* **authorization_code** (string) - Required - The authorization code provided by the issuer to retrieve the credential.
* **format** (string) - Required - The desired format of the credential (e.g., 'vc+sd-jwt').

### Request Example
```json
{
  "authorization_code": "some_auth_code_from_issuer",
  "format": "vc+sd-jwt"
}
```

### Response
#### Success Response (200)
- **credential** (string) - The issued credential in the requested format.
- **state** (string) - Optional: A state parameter to maintain context between requests.

#### Response Example
```json
{
  "credential": "ey...",
  "state": "some_state_value"
}
```
```

--------------------------------

### Docker Image Promotion Workflow

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Illustrates the automated or manual promotion of Docker images through different environments (dev, staging, rc, stable) as part of the CI/CD pipeline.

```text
[Commit → dev]
    ↓    build & push :dev
[Feature completed / Sprint end]
    ↓    promote → :staging
[Release candidate created]
    ↓    promote → :rc
[QA & penetration test passed]
    ↓    promote → :stable
```

--------------------------------

### Baking Vendor JCE Provider JAR into Custom Image

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/migration-guides/guide-3.1.x-to-3.2.x.md

When using a vendor JCE provider, copy its JAR file into the `/app/lib-ext/` directory and update the `ENTRYPOINT` to include it in the `-Xbootclasspath/a:` flag. This replaces the previous method of mounting JARs into `/lib`.

```dockerfile
FROM ghcr.io/swiyu-admin-ch/swiyu-issuer:3.0.0
USER 0
COPY vendor/primusX-java11.jar /app/lib-ext/primusX-java11.jar
# If the provider also ships a native library, add it the same way as 4a above
USER nonroot
ENTRYPOINT ["java", \
    "-Duser.timezone=Europe/Zurich", \
    "-Dspring.config.location=classpath:bootstrap.yml,classpath:application.yml,optional:file:/vault/secrets/database-credentials.yml", \
    "-Dfile.encoding=UTF-8", \
    "-Xbootclasspath/a:/app/lib-ext/primusX-java11.jar", \
    "-jar", "/app/app.jar"]

```

--------------------------------

### Issuer Service Deployment Diagram

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Illustrates a possible deployment configuration of the issuer service, showing the interaction between the Issuer Business System, Issuer Service, Postgres database, and Wallet.

```mermaid
flowchart LR
    issint[\Issuer Business System\]
    iss(Issuer Service)
    isdb[(Postgres)]
    wallet[Wallet]
    issint --Internal Network--> iss
    iss ---> isdb
    wallet --Web Access--> iss
```

--------------------------------

### Create Deferred Credential Offer

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/deferred.md

Use this endpoint to create a deferred credential offer. Set "deferred": true in credential_metadata. The credential_subject_data is optional and can be set later.

```bash
curl -X 'POST' \
  'http://localhost:8080/management/api/credentials' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{ \
  "metadata_credential_supported_id": [ \
    "university_example_sd_jwt" \
  ], \
  "credential_subject_data": { \
    "type": "Bachelor of Science", \
    "name":"Data Science", \
    "average_grade":"5.33" \
  }, \
  "credential_metadata": { \
    "deferred": true \
  }, \
  "offer_validity_seconds": 86400, \
  "deferred_offer_validity_seconds": 86400, \
  "credential_valid_until": "2030-01-01T19:23:24Z", \
  "credential_valid_from": "2025-01-01T18:23:24Z", \
  "status_lists": [ \
    "$STATUS_REGISTRY_URL" \
  ] \
}'
```

--------------------------------

### Minimal proof_types_supported configuration

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

This snippet demonstrates a minimal configuration for 'proof_types_supported' where only the JWT proof type is specified, allowing the wallet to choose the key storage.

```json
"jwt": {"proof_signing_alg_values_supported": ["ES256"]}
```

--------------------------------

### Build Dockerfile.securosys

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/examples/hsm/README.md

Builds a Docker image with HSM support using the Securosys Primus HSM via its JCE provider. Requires specifying the base issuer image.

```bash
docker build \
  --build-arg ISSUER_IMAGE=ghcr.io/swiyu-admin-ch/swiyu-issuer:3.0.0 \
  -f examples/hsm/Dockerfile.securosys \
  -t my-org/swiyu-issuer-hsm:3.0.0-securosys \
  .
```

--------------------------------

### Create Credential Offer

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Creates a new credential offer with specified subject data, validity periods, and associated status lists. Optionally includes VCT integrity information.

```bash
curl -X 'POST' \
  'http://localhost:8080/management/api/credentials' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{ \
  "metadata_credential_supported_id": [ \
    "university_example_sd_jwt" \
  ], \
  "credential_subject_data": { \
    "type": "Bachelor of Science", \
    "name":"Data Science", \
    "average_grade":"5.33" \
  }, \
  "offer_validity_seconds": 86400, \
  "credential_valid_until": "2030-01-01T19:23:24Z", \
  "credential_valid_from": "2025-01-01T18:23:24Z", \
  "status_lists": [ \
    "$STATUS_REGISTRY_URL" \
  ] \
}'
```

--------------------------------

### Configure Proxy Settings with JAVA_TOOL_OPTIONS

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/migration-guides/guide-3.1.x-to-3.2.x.md

Migrate proxy configurations from HTTP_PROXY, HTTPS_PROXY, and NO_PROXY to JAVA_TOOL_OPTIONS for the hardened image. This allows direct JVM system property configuration and custom port selection.

```yaml
```yaml
services:
  swiyu-issuer-service:
    image: ghcr.io/swiyu-admin-ch/swiyu-issuer:3.0.0
    environment:
      JAVA_TOOL_OPTIONS: >-
        -Dhttp.proxyHost=proxy.example.com
        -Dhttp.proxyPort=8080
        -Dhttps.proxyHost=proxy.example.com
        -Dhttps.proxyPort=8080
        -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.internal.example.com
```
```

--------------------------------

### Update Spring Profiles Environment Variable

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/migration-guides/guide-3.1.x-to-3.2.x.md

In v3.0.0, MY_SPRING_PROFILES is deprecated. Use the native Spring Boot variable SPRING_PROFILES_ACTIVE directly. This example shows the docker-compose configuration.

```yaml
services:
  swiyu-issuer-service:
    image: ghcr.io/swiyu-admin-ch/swiyu-issuer:3.0.0
    environment:
      SPRING_PROFILES_ACTIVE: prod,vault
```

--------------------------------

### Build Dockerfile.sunpkcs11

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/examples/hsm/README.md

Builds a Docker image with HSM support using the SunPKCS11 bridge. Requires specifying the base issuer image.

```bash
docker build \
  --build-arg ISSUER_IMAGE=ghcr.io/swiyu-admin-ch/swiyu-issuer:3.0.0 \
  -f examples/hsm/Dockerfile.sunpkcs11 \
  -t my-org/swiyu-issuer-hsm:3.0.0-sunpkcs11 \
  .
```

--------------------------------

### Build Custom Integrator Image Command

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/examples/README.md

Command to build the Docker image using the custom Dockerfile. Ensure you replace `swiyu-issuer:my-org` with your desired image name and tag.

```bash
docker build -f Dockerfile.dhi.integrator -t swiyu-issuer:my-org .

```

--------------------------------

### Build Custom Integrator Image with Custom CA Certificates

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/examples/README.md

Use this Dockerfile to build a custom swiyu-issuer image that includes your organization's private CA certificates. This is necessary when your infrastructure uses custom TLS certificates not trusted by default.

```dockerfile
# Stage 1: Build the custom trust store
FROM eclipse-temurin:21-jre AS cert-builder

# Arguments for the CA certificates folder and the trust store password
ARG CA_CERTS_FOLDER=./my-certs
ARG TRUSTSTORE_PASSWORD=changeit

# Copy the CA certificates into the builder image
COPY ${CA_CERTS_FOLDER} /usr/local/share/ca-certificates/

# Import the CA certificates into the Java trust store
RUN keytool -importcert -alias "custom-ca-$(date +%s)" -file "/usr/local/share/ca-certificates/$(ls /usr/local/share/ca-certificates/ | head -n 1)" -keystore "/etc/ssl/certs/java/cacerts" -storepass "${TRUSTSTORE_PASSWORD}" -noprompt

# Stage 2: Extend the official swiyu-issuer image
FROM swiyu-issuer:replace-with-official-tag

# Arguments for the trust store password
ARG TRUSTSTORE_PASSWORD=changeit

# Copy the updated Java trust store from the builder stage
COPY --from=cert-builder /etc/ssl/certs/java/cacerts /opt/java/openjdk/21-jre/lib/security/cacerts

# Set the trust store password as an environment variable (optional, for clarity)
ENV JAVA_TRUSTSTORE_PASSWORD=${TRUSTSTORE_PASSWORD}

# Set the entrypoint to the issuer's default entrypoint
ENTRYPOINT ["/app/entrypoint.sh"]

```

--------------------------------

### Create Status List

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/deferred.md

Initializes a status list for managing credential statuses like issued, revoked, or suspended. Store the returned statusRegistryUrl for future operations.

```bash
curl -X 'POST' \
  'http://localhost:8080/management/api/status-list' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{ \
  "type": "TOKEN_STATUS_LIST", \
  "maxLength": 100000, \
  "config": { \
    "bits": 2 \
  } \
}'
```

```json
{
    "id": "36f98a79-4be7-4978-bc46-071d8e40343a",
    "statusRegistryUrl": "your new $STATUS_REGISTRY_URL",
    "type": "TOKEN_STATUS_LIST",
    "maxListEntries": 100000,
    "remainingListEntries": 100000,
    "version": "1.0",
    "config": {
        "bits": 2
    }
}
```

--------------------------------

### Create Status List

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Initializes a token status list for managing credential revocation and suspension. Requires specifying the maximum number of entries and configuration for status bits.

```bash
curl -X 'POST' \
  'http://localhost:8080/management/api/status-list' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{ \
  "type": "TOKEN_STATUS_LIST", \
  "maxLength": 100000, \
  "config": { \
    "bits": 2 \
  } \
}'
```

--------------------------------

### Configure Status Registry with Client Key/Secret

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Set these properties in `application-local.yml` if you have a client key and secret for the status-list api-gateway.

```yaml
swiyu:
    status-registry:
    customer-key: "customer-key"
    customer-secret: "customer-secret"
```

--------------------------------

### Verify JAVA_HOME in Base Image

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/examples/README.md

Inspect the Docker image to find the JAVA_HOME environment variable, which helps determine the correct path for the Java trust store.

```bash
docker inspect <image> --format '{{range .Config.Env}}{{println .}}{{end}}' | grep JAVA_HOME

```

--------------------------------

### Verify Certificate Fingerprint (SHA-256)

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/certs/readme.md

Use this command to verify the integrity of a downloaded certificate file by checking its SHA-256 fingerprint against the publisher's provided fingerprint.

```bash
openssl x509 -in <file> -noout -fingerprint -sha256
```

--------------------------------

### Enable JWT Authentication and Configure JWKS Allowlist

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Set ENABLE_JWT_AUTH to true to require signed JWTs for writing calls. Optionally, provide a JWKS_ALLOWLIST with authorized public keys in JWK Set format.

```bash
ENABLE_JWT_AUTH=true
JWKS_ALLOWLIST={"keys":[{"kty":"EC","crv":"P-256","kid":"testkey","x":"_gHQsZT-CB_KvIfpvJsDxVSXkuwRJsuof-oMihcupQU","y":"71y_zEPAglUXBghaBxypTAzlNx57KNY9lv8LTbPkmZA"}]}
```

--------------------------------

### Semantic Versioning (SemVer) Format

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Defines the Semantic Versioning format used for this project, including MAJOR, MINOR, PATCH, and prerelease components.

```text
MAJOR.MINOR.PATCH[-rc][+BUILD]
```

--------------------------------

### Set Trusted Attestation Providers

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/migration-guides/guide-2.4.x-3.0.0.md

Environment variable to specify trusted attestation providers. If not set, no key attestations will be accepted.

```bash
TRUSTED_ATTESTATION_PROVIDERS=["did:example:123"]
```

--------------------------------

### Create status list entry

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Initializes a status list required for creating credential offers. This endpoint supports token status lists with revocation and suspension capabilities.

```APIDOC
## POST /management/api/status-list

### Description
Initializes a status list for managing credential statuses, such as revocation and suspension. The `statusRegistryUrl` returned must be stored for future use.

### Method
POST

### Endpoint
`/management/api/status-list`

### Parameters
#### Request Body
- **type** (string) - Required - Type of the status list, e.g., `TOKEN_STATUS_LIST`.
- **maxLength** (integer) - Required - The maximum number of entries the status list can hold.
- **config** (object) - Required - Configuration for the status list.
  - **bits** (integer) - Required - Number of bits used for each status list entry, determining the number of states.

### Request Example
```json
{
  "type": "TOKEN_STATUS_LIST",
  "maxLength": 100000,
  "config": {
    "bits": 2
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created status list.
- **statusRegistryUrl** (string) - The URL of the status registry, to be stored and used later.
- **type** (string) - The type of the status list.
- **maxListEntries** (integer) - The maximum number of entries allowed.
- **remainingListEntries** (integer) - The number of remaining entries available.
- **version** (string) - The version of the status list configuration.
- **config** (object) - The configuration details of the status list.
  - **bits** (integer) - The number of bits used for status entries.

### Response Example
```json
{
    "id": "36f98a79-4be7-4978-bc46-071d8e40343a",
    "statusRegistryUrl": "your new $STATUS_REGISTRY_URL",
    "type": "TOKEN_STATUS_LIST",
    "maxListEntries": 100000,
    "remainingListEntries": 100000,
    "version": "1.0",
    "config": {
        "bits": 2
    }
}
```
```

--------------------------------

### Create Deferred Credential Offer

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/deferred.md

Creates a deferred credential offer. To create a deferred offer, set `"deferred": true` in the `credential_metadata`. The `credential_subject_data` is optional and can be set later.

```APIDOC
## POST /management/api/credentials

### Description
Creates a deferred credential offer. This endpoint allows for the creation of offers where the credential subject data may not be known at the time of offer creation.

### Method
POST

### Endpoint
/management/api/credentials

### Parameters
#### Request Body
- **metadata_credential_supported_id** (array[string]) - Required - The ID(s) of the supported credential configuration.
- **credential_subject_data** (object) - Optional - The data for the credential subject. Can be an empty object if not known beforehand.
- **credential_metadata** (object) - Required - Metadata for the credential. Must include `"deferred": true` for deferred offers.
  - **deferred** (boolean) - Required - Set to `true` to create a deferred credential offer.
- **offer_validity_seconds** (integer) - Required - The validity period of the offer in seconds.
- **deferred_offer_validity_seconds** (integer) - Required - The validity period of the deferred offer in seconds.
- **credential_valid_until** (string) - Required - The date and time until which the credential is valid (ISO 8601 format).
- **credential_valid_from** (string) - Required - The date and time from which the credential is valid (ISO 8601 format).
- **status_lists** (array[string]) - Required - URLs for status lists.

### Request Example
```json
{
  "metadata_credential_supported_id": [
    "university_example_sd_jwt"
  ],
  "credential_subject_data": {
    "type": "Bachelor of Science",
    "name":"Data Science",
    "average_grade":"5.33"
  },
  "credential_metadata": {
    "deferred": true
  },
  "offer_validity_seconds": 86400,
  "deferred_offer_validity_seconds": 86400,
  "credential_valid_until": "2030-01-01T19:23:24Z",
  "credential_valid_from": "2025-01-01T18:23:24Z",
  "status_lists": [
    "$STATUS_REGISTRY_URL"
  ]
}
```

### Response
#### Success Response (200)
- **management_id** (string) - The unique identifier for the management of this offer.
- **offer_deeplink** (string) - A deep link to be passed to the wallet application.

#### Response Example
```json
{
    "management_id": "6444cd65-f550-4934-af85-1bd295cea1ba",
    "offer_deeplink": "swiyu://?credential_offer=%7B%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%2206b5424f-8baf-4eaa-a770-7fa8ab7a85a7%22%7D%7D%2C%22version%22%3A%221.0%22%2C%22credential_issuer%22%3A%22http%3A%2F%2Flocalhost%3A8080%2F%22%2C%22credential_configuration_ids%22%3A%5B%22university_example_sd_jwt%22%5D%7D"
}
```
```

--------------------------------

### Credential Offer Creation Response

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

Response upon creating a credential offer, containing a management ID for status tracking and a deep link for the wallet application to initiate the credential process.

```json
{
    "management_id": "6444cd65-f550-4934-af85-1bd295cea1ba",
    "offer_deeplink": "swiyu://?credential_offer=%7B%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%2206b5424f-8baf-4eaa-a770-7fa8ab7a85a7%22%7D%7D%2C%22version%22%3A%221.0%22%2C%22credential_issuer%22%3A%22http%3A%2F%2Flocalhost%3A8080%2F%22%2C%22credential_configuration_ids%22%3A%5B%22university_example_sd_jwt%22%5D%7D"
}
```

--------------------------------

### New Issuer Metadata Claims Format with Path Pointers

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/migration-guides/guide-2.4.x-3.0.0.md

This JSON structure demonstrates the new `credential_metadata.claims` format using claims path pointers, which is the recommended approach for issuer metadata.

```json
{
    "credential_metadata": {
        "claims": [
            {
                "mandatory": true,
                "path": [
                    "type"
                ]
            },
            {
                "mandatory": true,
                "path": [
                    "name"
                ]
            },
            {
                "mandatory": false,
                "path": [
                    "average_grade"
                ]
            },
            {
                "path": [
                    "languages",
                    null
                ]
            }
        ]
    }
}
```

--------------------------------

### Generate EC Public Key from Private Key

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Use OpenSSL to generate the public key from a previously generated private key.

```bash
openssl ec -in private.pem -pubout -out ec_public.pem
```

--------------------------------

### Generate EC Private Key

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Use OpenSSL to generate an EC 256 private key. Remember to keep private keys secure.

```bash
openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
```

--------------------------------

### Configure Status Registry with Refresh Token

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Set these properties in `application-local.yml` if you are using a refresh token flow for the status-list api-gateway.

```yaml
swiyu:
    status-registry:
        api-url: "https://api-url"
        enable-refresh-token-flow: true
        bootstrap-refresh-token: "your refresh token"
```

--------------------------------

### Update Credential Offer Status to Ready

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/deferred.md

The business issuer can update the status of a credential offer to 'READY' using the management API. This is useful if the offer data is already set.

```bash
curl -X 'PATCH' 'http://localhost:8080/management/api/credentials/$MANAGEMENT_ID/status?credentialStatus=READY' -H 'accept: application/json'
```

--------------------------------

### OpenID Connect Configuration Response

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/issuance.md

This JSON response provides the issuer's base URL and the token endpoint, which are essential for subsequent authentication steps.

```json
{
    "issuer": "http://localhost:8080",
    "token_endpoint": "http://localhost:8080/oid4vci/api/token"
}
```

--------------------------------

### Update Credential Offer Data

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/deferred.md

The business issuer can update the offer data, which automatically sets the credential offer's status to 'READY'. This allows for providing details like type, name, and average grade.

```bash
curl -X 'PATCH' \
  'http://localhost:8080/management/api/credentials/$MANAGEMENT_ID' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "Bachelor of Science",
    "name":"Data Science",
    "average_grade":"5.33"
  }'
```

--------------------------------

### Credential Offer Status Update Response

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/deferred.md

The response confirms the update of the credential offer's ID and its new status, which is set to 'READY'.

```json
{
    "id": "$MANAGEMENT_ID",
    "status": "READY"
}
```

--------------------------------

### Enable Registry Health Checks

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/migration-guides/guide-2.4.x-3.0.0.md

Environment variable to enable status registry health checks. Ensure registry endpoint and credentials are configured if enabled.

```bash
REGISTRY_HEALTH_CHECKS_ENABLED=true
```

--------------------------------

### Sign Commit with Git

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/CONTRIBUTING.md

Use the '-s' flag with git commit to automatically sign off your commit message, certifying your right to submit the work under the project's license.

```bash
git commit -s
```

--------------------------------

### Update OpenAPI Spec

Source: https://github.com/swiyu-admin-ch/swiyu-issuer/blob/main/README.md

Use this command to update the OpenAPI specification file. This is typically done during the verification phase of the build.

```bash
mvn verify -P generate-doc
```
Tokens:
Raw