Skip to main content
Manage Extension

Turn an extension on or off

PUT/v4/config/platform/extension/{extensionId}

Turns one extension on or off for your organisation, and chooses or changes the signing key of its definitions. With an API key of a sandbox organisation, the call acts on that sandbox organisation.

Turning an extension on prepares what it needs in your organisation wallet. Most extensions make system-managed presentation definitions (KYC, Age Verification, Document Signing, the TS12 payment extensions) or credential definitions (PID, Photo ID and payment credential issuance). Turning it off deletes them again. Read the extension afterwards to get the IDs of these definitions.

An extension that makes definitions takes a signing key (takesSigningKey in the list): send signingKeyId, an X.509 key of the organisation with a certificate chain. A sandbox organisation signs with the keys of its main organisation. The API never selects a key for you:

  • {"enabled": true, "signingKeyId": "<key id>"} on an extension that is off turns it on: the definitions are made with the key, and the status is enabled.
  • {"enabled": true} without a key on such an extension that is off gives the status awaitingKey: nothing is made, and the extension does not run until you send the key.
  • {"enabled": true, "signingKeyId": "<key id>"} on an extension that is enabled changes the key of all its definitions in one step. No definition is made again, and the settings of the extension stay.
  • {"enabled": true} without a key on an extension that is enabled or awaitingKey changes nothing.
  • {"enabled": false} turns the extension off and deletes its definitions. Do not send signingKeyId with it.

An extension that takes no signing key turns on at once with {"enabled": true}, and each such request runs the full enable again, so read the status first:

  • oidc (Passwordless Login) makes the OpenID Provider of the organisation. It takes no signing key in your organisation. The answer then holds metadataUrl, the discovery URL for your identity and access management system. Turning it off deletes the OpenID Connect clients that you made.
  • openidConformance takes no signing key: it makes its own signing keys with test certificates in the local key store. When the HSM partition of the key store has no room for a new key, the answer is 507.

documentSigning: turning it off also deletes the uploaded PDF files. An extension that waits for its key keeps them.

Authorizations

  • Authorizationstringheaderrequired

    Your API key with the prefix ApiKey: ApiKey <your-api-key>. Get an API key.

    Scope:extensions:update

Path parameters

  • extensionIdenum<string>required

    The ID of the extension, as the key in the answer of the list call. oidc is Passwordless Login, openidConformance prepares the organisation for OpenID Foundation conformance runs.

    Available options:oidc,documentSigning,kyc,ageVerification,paymentIssuance,paymentAuthorisationIssuer,paymentAuthorisationMerchant,accountInformationAccess,recurringPaymentMandate,riskBasedAuthentication,pidIssuance,photoIDIssuance,openidConformance

    Example:"kyc"

Body

application/json
  • enabledbooleanrequired

    true turns the extension on, false turns it off.

    Example:true

  • signingKeyIdstring

    Only with "enabled": true, and only for an extension that takes a signing key (takesSigningKey in the list): the X.509 signing key of the organisation that all definitions of the extension sign with. The key must have a certificate chain. Get the key IDs with the key API of the OpenID4VC API (GET /v4/config/ows/key-management/keys). Without it, an extension that takes a signing key and is off gets the status awaitingKey and nothing is made. On an extension that is enabled (or waits with definitions), it changes the key of all its definitions.

    Example:"c6b150f6dcd446459a66192e8f8303d1"

Response

application/json

The extension has the new status.

  • statusenum<string>

    The new status. awaitingKey: the extension takes a signing key and you turned it on without one; it does not run until you send the key.

    Available options:disabled,awaitingKey,enabled

    Example:"enabled"

  • signingKeyIdstring

    The signing key that all definitions of the extension share. An empty string when the extension is not enabled, or when it takes no signing key.

    Example:"c6b150f6dcd446459a66192e8f8303d1"

  • metadataUrlstring<uri>

    Only for the oidc extension when it is enabled: the OpenID Connect discovery URL of the organisation (or of the sandbox organisation of the request). Give it to your identity and access management system.