Update global configuration
PUT/v2/config/digital-wallet/openid/issuer/global-configuration
Updates the global configuration of the OID4VCI issuer. An organisation has one issuer global configuration, so the path has no identifier.
Send only the fields that you want to change. A field that you leave out keeps its stored value. The service keeps the current logo and cover image of credentialBranding, and it ignores those two URLs in the request body.
Request
- application/json
Body
required
The issuance settings to change. All fields are optional. A field that you leave out keeps its stored value.
Possible values: >= 1 and <= 3650
Default validity, in days, of a credential whose configuration sets none. 1 to 3650; the default is 180. 0 means not set.
Possible values: >= 60 and <= 315360000
Default validity, in seconds, of a credential whose configuration sets none. 60 to 315360000. When set, it has precedence over credentialExpirationInDays. 0 means not set.
credentialBranding object
Default display properties of the credential card in wallet UIs.
Default display name for credentials in wallet UIs, as specified in the OID4VCI Credential Issuer Metadata.
Default human-readable description for credentials displayed in wallet UIs.
Default hex colour code for the credential card background (e.g. #FFFFFF).
Default hex colour code for text on the credential card (e.g. #000000).
logo object
Logo of the credential card. The service sets uri itself.
Alternative text for the logo image.
When true, the wallet must encrypt the OpenID for Verifiable Credentials Issuance (OID4VCI) Credential Request using the issuer's encryption key.
Possible values: >= 1 and <= 31536000
Time-to-live (in seconds) for the OID4VCI Authorization Request. 1 to 31536000; the default is 60. 0 means not set.
Possible values: [jwk, did:key, cose_key]
Default holder key binding methods that the issuer publishes in the OID4VCI Credential Issuer Metadata. The list is a template for new credential definitions of all formats, so it always has cose_key: the service adds cose_key when the list does not have it. null or [] stores the default jwk and cose_key. A credential definition keeps the rule of its format: mso_mdoc has cose_key only, dc+sd-jwt and jwt_vc_json have did:key or jwk, or both. An unknown value gives 400 (Invalid credential binding method(s): [<values>]).
Possible values: >= 1 and <= 2592000
Minimum polling interval (in seconds) for the wallet when using the OID4VCI Deferred Credential Endpoint. 1 to 2592000; the default is 5. 0 means not set.
notificationEndpointEnabled object
Controls the OID4VCI Notification Endpoint.
When true, the issuer publishes the Notification Endpoint for wallets that use OpenID4VCI 1.0.
issuerMetadata object
Signing settings for the OID4VCI Credential Issuer Metadata.
When true, the issuer publishes the Credential Issuer Metadata as a signed JWT.
Identifier of the key that signs the Credential Issuer Metadata. Without it, the default key of the organisation signs.
Possible values: [x509, did:key]
Format of the signing key: x509 or did:key. Without it, the format is x509 when the key has a certificate chain, else did:key. x509 needs a key with a certificate chain, else the service answers 400.
Possible values: >= 60 and <= 5184000
How long an access token of this issuer is valid, in seconds. 60 to 5184000; the default is 900. The wallet gets a new one with its refresh token.
Possible values: >= 300 and <= 315360000
How long a refresh token of this issuer is valid, in seconds. 300 to 315360000; the default is 31536000. It must be longer than accessTokenLifetimeInSeconds.
Possible values: >= 1 and <= 86400
Time-to-live (in seconds) for the authorization code (RFC 6749 §4.1.2). 1 to 86400; the default is 60. After this period the code expires and can no longer be exchanged for a token.
Possible values: >= 60 and <= 86400
Time-to-live (in seconds) for the pre-authorised code of the Pre-Authorized Code Flow. 60 to 86400; the default is 600.
Possible values: >= 1 and <= 86400
Time-to-live (in seconds) for the c_nonce issued to the wallet at the token/nonce endpoint. 1 to 86400; the default is 300. After this period the nonce expires and the wallet must request a fresh one before it can prove key possession.
The authorisation server supports DPoP (RFC 9449): the metadata lists dpop_signing_alg_values_supported and the access token is bound to the key of the wallet's DPoP proof. Off by default. When off, the token endpoint issues Bearer tokens. Turning it off also turns off dpopRequired.
Makes the DPoP proof (RFC 9449) mandatory at the token endpoint: token requests without a proof are rejected. Turning it on also turns on dpopEnabled. dpopEnabled: false together with dpopRequired: true gives 400.
When true, one credential request can carry more than one proof, and the issuer issues one credential for each proof. Needs batchSize.
Possible values: >= 2 and <= 100
The most proofs, and so credentials, that one credential request can carry. 2 to 100.
When true (the default), the Credential Issuer Metadata keeps the iGrant.io issuer display extensions (location and background_image).
When true, the Credential Issuer Metadata announces DEFLATE compression (zip DEF) for an encrypted Credential Request. Defaults to false.
When true, the Credential Issuer Metadata announces DEFLATE compression (zip DEF) for an encrypted Credential Response, and the issuer compresses the response when the request asks for it. Defaults to false.
Responses
- 200
- 400
- 401
- 404
- 500
The issuer updated the global configuration.
Response Headers
- application/json
- Schema
- Example (from schema)
Schema
globalConfiguration objectrequired
The global configuration after the update.
Record identifier of the global configuration. The service makes this value when it saves the record. It has the same value as globalConfigurationId.
Unique identifier of the issuer global configuration. An organisation has one issuer global configuration, so the read and update operations do not use this value.
Identifier of the OpenID wallet deployment that holds this configuration.
Default validity, in days, of a credential whose configuration sets none. The default is 180.
Default validity, in seconds, of a credential whose configuration sets none. When present, it has precedence over credentialExpirationInDays.
credentialBranding objectrequired
Default display properties of the credential card in wallet UIs. The service always returns this object.
Default display name for credentials in wallet UIs, as specified in the OID4VCI Credential Issuer Metadata.
Default human-readable description for credentials displayed in wallet UIs.
Default hex colour code for the credential card background (e.g. #FFFFFF).
Default hex colour code for text on the credential card (e.g. #000000).
logo objectrequired
Logo that wallets show on the credential card. The service sets uri and ignores the value in the request body.
URL of the default logo displayed on credential cards in wallet UIs. The service sets this URL to the organisation logo, and it changes the URL to the configuration logo after an upload to the logo image operation.
Alt text for the logo image, used for accessibility.
backgroundImage objectrequired
Background image that wallets show on the credential card. The service sets uri and ignores the value in the request body.
URL of the default background image for credential cards.
When true, the wallet must encrypt the OpenID for Verifiable Credentials Issuance (OID4VCI) Credential Request using the issuer's encryption key.
Time-to-live (in seconds) for the OID4VCI Authorization Request. After this period, the credential offer expires.
Possible values: [jwk, did:key, cose_key]
Default holder key binding methods that the issuer publishes in the OID4VCI Credential Issuer Metadata. The list always has cose_key, and without a stored value it is jwk and cose_key. It is a template for new credential definitions: each credential definition keeps the methods of its format.
Minimum polling interval (in seconds) for the wallet when using the OID4VCI Deferred Credential Endpoint.
notificationEndpointEnabled object
Shows whether the issuer publishes the OID4VCI Notification Endpoint. The service omits this field when the configuration holds no value.
When true, the issuer publishes the Notification Endpoint for wallets that use OpenID4VCI 1.0.
issuerMetadata object
Signing settings of the OID4VCI Credential Issuer Metadata. The service omits this field when the configuration holds no value.
When true, the issuer publishes the Credential Issuer Metadata as a signed JWT.
Key identifier of the key that signs the Credential Issuer Metadata. The service omits this field when signed metadata is off.
Format of the signing key: x509 or did:key.
How long an access token of this issuer is valid, in seconds. The wallet gets a new one with its refresh token.
How long a refresh token of this issuer is valid, in seconds.
Time-to-live (in seconds) for the pre-authorised code of the Pre-Authorized Code Flow.
Sets the time-to-live (in seconds) for the authorization code (RFC 6749 §4.1.2). After this period the code expires and can no longer be exchanged for a token.
The authorisation server supports DPoP (RFC 9449): the metadata lists dpop_signing_alg_values_supported and the access token is bound to the key of the wallet's DPoP proof. Off by default. When off, the token endpoint issues Bearer tokens. Turning it off also turns off Require DPoP.
Makes the DPoP proof (RFC 9449) mandatory at the v1.0 token endpoint: token requests without a proof are rejected. Needs Enable DPoP; turning it on also turns on Enable DPoP. Applies at the authorisation server, immediately.
Sets the time-to-live (in seconds) for the c_nonce issued to the wallet at the token/nonce endpoint. After this period the nonce expires and the wallet must request a fresh one before it can prove key possession.
When true, one credential request can carry more than one proof, and the issuer issues one credential for each proof.
The most proofs, and so credentials, that one credential request can carry.
When true, the Credential Issuer Metadata keeps the iGrant.io issuer display extensions (location and background_image).
When true, the Credential Issuer Metadata announces DEFLATE compression for an encrypted Credential Request.
When true, the Credential Issuer Metadata announces DEFLATE compression for an encrypted Credential Response.
Unix timestamp (in seconds) when this configuration was created.
Unix timestamp (in seconds) when this configuration was last modified.
settingLimits objectrequired
The rule of each numeric setting of the issuer global configuration, as in the read operation.
property name* object
The rule of one numeric setting of the issuer global configuration. The wallet owns these rules.
The smallest value that the update operation accepts.
The largest value that the update operation accepts.
The value that the issuer uses when the setting is not set (null). null when the setting has no default.
The unit of the value, for example seconds.
When true, the value 0 in the configuration also means that the setting is not set.
{
"globalConfiguration": {
"id": "665f2b8c9a1d4e0012ab34cd",
"globalConfigurationId": "b7d1f4a2-8c3e-4a91-9f52-0d3c6e7a1b45",
"openIdOrganisationId": "string",
"credentialExpirationInDays": 180,
"credentialExpirationInSeconds": 0,
"credentialBranding": {
"name": "string",
"description": "string",
"backgroundColor": "#FFFFFF",
"textColor": "#000000",
"logo": {
"uri": "string",
"altText": "string"
},
"backgroundImage": {
"uri": "string"
}
},
"credentialRequestEncryptionRequired": true,
"authorizationRequestExpiry": 300,
"credentialBindingMethods": [
"jwk",
"cose_key"
],
"credentialResponseInterval": 5,
"notificationEndpointEnabled": {
"version_01": true
},
"issuerMetadata": {
"signedMetadataEnabled": true,
"cryptographicKeyIdentifier": "string",
"cryptographicKeyFormat": "string"
},
"accessTokenLifetimeInSeconds": 900,
"refreshTokenLifetimeInSeconds": 31536000,
"preAuthorisedCodeLifetimeInSeconds": 600,
"authorizationCodeExpiryInSeconds": 300,
"dpopEnabled": false,
"dpopRequired": false,
"nonceExpiryInSeconds": 300,
"batchIssuanceEnabled": true,
"batchSize": 0,
"includeIssuerDisplayExtensions": true,
"credentialRequestCompressionEnabled": true,
"credentialResponseCompressionEnabled": true,
"createdAt": 1747011600,
"updatedAt": 1747011600
},
"settingLimits": {}
}
The organisation is unknown, the OpenID wallet is not deployed, a value is not valid (see settingLimits of the read operation), refreshTokenLifetimeInSeconds is not longer than accessTokenLifetimeInSeconds, batchIssuanceEnabled is true without batchSize, the key of signed issuer metadata is not usable, the body has an unknown field, or the issuer cannot save the configuration.
Response Headers
- application/json
- Schema
- Example (from schema)
Schema
{
"errorCode": 400,
"errorDescription": "Bad input parameter"
}
Unauthorized
Response Headers
- application/json
- Schema
- Example (from schema)
Schema
{
"errorCode": 400,
"errorDescription": "Bad input parameter"
}
Global configuration not found. The wallet makes the configuration when it deploys the organisation wallet, so this error comes only when that step failed. There is no create operation: contact support.
Response Headers
- application/json
- Schema
- Example (from schema)
Schema
{
"errorCode": 400,
"errorDescription": "Bad input parameter"
}
Internal server error
Response Headers
- application/json
- Schema
- Example (from schema)
Schema
{
"errorCode": 400,
"errorDescription": "Bad input parameter"
}