#Create a Credential Offer

This guide walks you through creating a credential offer from one or more existing profiles. The offer generates an OID4VCI credential offer URL that can be claimed by any compliant wallet.

#Prerequisites

Before creating an offer, ensure you have:

Issuer2 API running
Credential Profile configured — or use one of the ready-made default profiles

#Create an Offer

CURL

Endpoint: POST /issuer2/credential-offers | API Reference

#Example Request

curl -X 'POST' \
  'http://localhost:7005/issuer2/credential-offers' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "profileId": "openBadgeCredential",
    "authMethod": "PRE_AUTHORIZED"
  }'

Body Parameters

profileId: String (required) - The ID of the credential profile to use.
authMethod: String (required) - Authentication method: PRE_AUTHORIZED or AUTHORIZED.
valueMode: String (optional) - How the credential offer is delivered (default: BY_REFERENCE). BY_REFERENCE — offer URL contains a reference, wallet fetches the full offer. BY_VALUE — full credential offer embedded in the URL.
issuerStateMode: String (optional) - Whether to include issuer state for AUTHORIZED offers (default: INCLUDE). OMIT — no issuer state. INCLUDE — include issuer state for session correlation with authorization servers.
expiresInSeconds: Integer (optional) - Offer validity duration in seconds (default: 300). Set to -1 for no expiration.
txCode: Object (optional) - Transaction code (PIN) configuration for pre-authorized flow. See Transaction Code Configuration.
txCodeValue: String (optional) - Specific PIN value (if not provided, one is generated).
runtimeOverrides: Object (optional) - Override profile values for this offer. See Runtime Overrides.
sessionId: String (optional) - Session ID for the offer. If not provided, a random session ID will be generated.

#Example Response

{
  "offerId": "abc123-def456-ghi789",
  "profileId": "openBadgeCredential",
  "authMethod": "PRE_AUTHORIZED",
  "expiresAt": 1704067500000,
  "credentialOffer": "openid-credential-offer://?credential_offer_uri=http%3A%2F%2Flocalhost%3A7005%2Fopenid4vci%2Fcredential-offer%3Fid%3Dabc123-def456-ghi789"
}

Response Fields

offerId: String - Unique identifier for this offer.
profileId: String - The profile used to create this offer.
authMethod: String - The authentication method.
issuerStateMode: String - The issuer state mode (for authorized flow).
expiresAt: Long - Unix timestamp (ms) when the offer expires.
txCodeValue: String - The PIN value (only for pre-authorized flow with txCode).
credentialOffer: String - The OID4VCI credential offer URL.

Send either a single-profile body (profileId plus optional runtimeOverrides) or a multi-credential body (credentials[]). Do not send both, and do not put top-level runtimeOverrides on a credentials[] request.

#Multiple Credentials

Use credentials[] to offer several profiles, or the same profile with different credentialData / credentialStatus overrides, in one URL. The wallet redeems each offered item with a separate Credential Endpoint request.

curl -X POST 'http://localhost:7005/issuer2/credential-offers' \
  -H 'Content-Type: application/json' \
  -d '{
    "credentials": [
      { "profileId": "openBadgeCredential" },
      { "profileId": "isoMdl" }
    ],
    "authMethod": "PRE_AUTHORIZED"
  }'

Each item can carry its own runtimeOverrides. Do not send top-level runtimeOverrides on a credentials[] request.

curl -X POST 'http://localhost:7005/issuer2/credential-offers' \
  -H 'Content-Type: application/json' \
  -d '{
    "credentials": [
      {
        "profileId": "openBadgeCredential",
        "runtimeOverrides": {
          "credentialData": {
            "credentialSubject": {
              "achievement": { "name": "Bachelor of Science" }
            }
          }
        }
      },
      { "profileId": "isoMdl" }
    ],
    "authMethod": "PRE_AUTHORIZED"
  }'

The create-offer response for a credentials[] request has the same common fields (offerId, authMethod, expiresAt, credentialOffer, …) but no profileId and no credentials array. The wallet reads the offered configuration IDs from the OID4VCI offer itself.

If two items share the same credential_configuration_id (for example the same profile twice with different datasets), the wallet must request authorization_details at the token endpoint and then use credential_identifier on each Credential Request.

A homogeneous cryptographic batch — multiple holder proofs (proofs.jwt) for one of those items on a single Credential Request — is separate. The shipped issuer-service.conf enables it with batchCredentialIssuance { batchSize = 10 }. See Issuer Service. Each proof issues a copy of the selected item's dataset and status entry.

#Examples

#Pre-Authorized Flow with PIN

Require a PIN for additional security:

curl -X POST 'http://localhost:7005/issuer2/credential-offers' \
  -H 'Content-Type: application/json' \
  -d '{
    "profileId": "openBadgeCredential",
    "authMethod": "PRE_AUTHORIZED",
    "txCode": {
      "input_mode": "numeric",
      "length": 6,
      "description": "Please enter the PIN sent to your email"
    }
  }'

Response includes the PIN:

{
  "offerId": "abc123-def456-ghi789",
  "profileId": "openBadgeCredential",
  "authMethod": "PRE_AUTHORIZED",
  "expiresAt": 1704067500000,
  "txCodeValue": "123456",
  "credentialOffer": "openid-credential-offer://..."
}

#Pre-Authorized Flow with Custom PIN

Specify your own PIN value:

curl -X POST 'http://localhost:7005/issuer2/credential-offers' \
  -H 'Content-Type: application/json' \
  -d '{
    "profileId": "openBadgeCredential",
    "authMethod": "PRE_AUTHORIZED",
    "txCode": {
      "input_mode": "numeric",
      "length": 4
    },
    "txCodeValue": "1234"
  }'

#Authorization Code Flow

For user authentication via external IdP:

curl -X POST 'http://localhost:7005/issuer2/credential-offers' \
  -H 'Content-Type: application/json' \
  -d '{
    "profileId": "identityCredentialSdJwt",
    "authMethod": "AUTHORIZED",
    "issuerStateMode": "INCLUDE"
  }'

issuerStateMode: "INCLUDE" lets the Issuer2 API correlate the authorization request it receives back with this offer's issuance session. See Authorization Code Flow for the full sequence, including how (and when) issuer_state is forwarded to the external authorization server.

issuer_state can be viewed as a mechanism in OpenID4VCI for correlating a Credential Offer with the later Authorization Request in the Authorization Code Flow. The issuer creates it, the wallet treats it as opaque, and if it is present in the offer the wallet sends it back in the Authorization Request. Issuer2 includes issuer_state by default for AUTHORIZED offers. If you explicitly set issuerStateMode to OMIT, do not use runtimeOverrides; offer-specific overrides require issuer-state correlation and the request is rejected.

You can run this example without setting up an identity provider. Out of the box it uses a hosted walt.id test provider — open the offer in a wallet and log in as jane@walt.id / jane. Because the identityCredentialSdJwt profile maps given_name and family_name from the ID token, the issued credential is populated with Jane's name from her login.

#Offer by Value

Embed the full offer in the URL (useful for offline scenarios):

curl -X POST 'http://localhost:7005/issuer2/credential-offers' \
  -H 'Content-Type: application/json' \
  -d '{
    "profileId": "openBadgeCredential",
    "authMethod": "PRE_AUTHORIZED",
    "valueMode": "BY_VALUE"
  }'

#Custom Expiration

Set a longer expiration time:

curl -X POST 'http://localhost:7005/issuer2/credential-offers' \
  -H 'Content-Type: application/json' \
  -d '{
    "profileId": "openBadgeCredential",
    "authMethod": "PRE_AUTHORIZED",
    "expiresInSeconds": 3600
  }'

#Runtime Overrides

Override profile values for a specific offer — including the signing key, not just the credential data:

curl -X POST 'http://localhost:7005/issuer2/credential-offers' \
  -H 'Content-Type: application/json' \
  -d '{
    "profileId": "openBadgeCredential",
    "authMethod": "PRE_AUTHORIZED",
    "runtimeOverrides": {
      "issuerKey": {
        "type": "jwk",
        "jwk": {
          "kty": "EC",
          "d": "AIZNxblzgCJ4mFW76wpzilIuXofOk1yEccgYMr9-isQ",
          "crv": "P-256",
          "kid": "bx1HUtz7-qAwslnQTDrxk1_kKWJ5kyl6KZCZUqGPH9A",
          "x": "j0zPEQ3j3NkdhSZpkQD4Q1XIQTEDNS21X4I_WH5Z7w4",
          "y": "zl6YSyhrfTP5KP7R7t0xuWeFsqV0Z-nwbmd_61yBbFo"
        }
      },
      "issuerDid": "did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2Iiwia2lkIjoiYngxSFV0ejctcUF3c2xuUVREcnhrMV9rS1dKNWt5bDZLWkNaVXFHUEg5QSIsIngiOiJqMHpQRVEzajNOa2RoU1pwa1FENFExWElRVEVETlMyMVg0SV9XSDVaN3c0IiwieSI6InpsNllTeWhyZlRQNUtQN1I3dDB4dVdlRnNxVjBaLW53Ym1kXzYxeUJiRm8ifQ",
      "credentialData": {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          "https://www.w3.org/2018/credentials/examples/v1"
        ],
        "type": ["VerifiableCredential", "OpenBadgeCredential"],
        "credentialSubject": {
          "achievement": {
            "name": "Master of Computer Science"
          }
        }
      },
      "notifications": {
        "webhook": {
          "url": "https://my-server.com/webhook/special-offer"
        }
      }
    }
  }'

issuerKey (and issuerDid/x5Chain) override the profile's default signing key for this offer only — useful for issuing a one-off credential with a different key without touching the profile itself. Provide both together, since a mismatched key/DID pair will fail to sign.

#Available Override Fields

Field	Description
`issuerDid`	Override the issuer DID
`issuerKey`	Override the signing key
`x5Chain`	Override the X.509 certificate chain
`credentialData`	Override the credential data
`mapping`	Override the data mapping
`selectiveDisclosure`	Override the SD-JWT selective disclosure configuration
`idTokenClaimsMapping`	Override ID token claims mapping
`mDocNameSpacesDataMappingConfig`	Override mDoc data mapping
`authorizedTransactionDataTypes`	Override mDoc OpenID4VP transaction-data types authorized in the MSO `KeyAuthorizations`
`msoData`	Field-merge MSO `ValidityInfo` (`validFrom`, `validUntil`, `expectedUpdate`) onto the profile. mDoc only.
`credentialStatus`	Override credential status configuration
`notifications`	Override notification settings
`expectedCredentialProofKeyJwk`	Expected holder proof public key (JWK)

#Transaction Code Configuration

The txCode object configures PIN requirements:

Property	Type	Description
`input_mode`	String	Input type: `numeric` or `text`
`length`	Integer	Length of the PIN
`description`	String	Description shown to the user

#Using the Credential Offer URL

The credentialOffer URL can be:

Displayed as QR Code – User scans with their wallet app
Sent as Deep Link – User clicks link on mobile device
Embedded in Email/Message – User clicks to open in wallet

#Example Decoded Offer URL

openid-credential-offer://?credential_offer_uri=http://localhost:7005/openid4vci/credential-offer?id=abc123-def456-ghi789

#Next Steps

Notifications – Configure webhook notifications
Data Functions – Populate credentials with dynamic data
Issuer Service – Enable Credential Endpoint proofs.jwt batch issuance

Last updated on September 30, 2026

Overview Credential Status