Skip to main content

Config Bundle Format

The format of configuration documents, tenant config folders and export bundles, as read by the startup import, the bundle API and the CLI. For the workflow (validate, export, plan, import), see Configuration as code.

Document envelope​

Every portable resource is one JSON document:

{
"$schema": "https://eudiplo.dev/schemas/v4/PresentationConfigFile.schema.json",
"metadata": { "generation": 3, "ownership": "file-managed" },
"spec": { "id": "age-check" }
}
FieldRequiredMeaning
$schemayesResource type and format version. Only the canonical URLs below are accepted; they are resolved from schemas bundled with the backend and CLI, never fetched.
metadata.generationnoInteger ≥ 1. A bundle import whose generation is lower than the stored one is blocked (STALE_GENERATION); the startup import skips that resource instead.
metadata.ownershipnounmanaged or file-managed. Reported on export, where a detached resource is reported as unmanaged; ignored on import, which always records file-managed.
specyesThe desired configuration, without runtime state. The ID is spec.id, for clients spec.clientId, which is unique across tenants: a client ID another tenant uses blocks the plan (CLIENT_ID_TAKEN).

Tenant, KMS and issuance settings and the key chain defaults exist once per tenant and have no ID. In tenant config folders, the importer also accepts bare files (only the spec content) at the known paths and wraps them; a document with an unknown $schema or a newer version than the backend supports is rejected. A bare file names no version, so it is read as version 1, except key chain, key chain defaults, KMS, tenant and presentation files (format versions): prefer documents, which GET /api/config-bundles/resources/:kind/:id/document and the Web Client's download buttons write (single resources).

Resource types and versions​

The URL is https://eudiplo.dev/schemas/v<version>/<File>.schema.json. Older versions are migrated on import and by eudiplo config upgrade; a backend rejects versions newer than its own.

Kind<File>Current versionSingleton
TenantTenantConfigFile4yes
ClientClientConfigFile2
KmsConfigKmsConfigFile2yes
KeyChainKeyChainConfigFile4
KeyChainDefaultsKeyChainDefaultsConfigFile2yes
IssuanceConfigIssuanceConfigFile7yes
CredentialConfigCredentialConfigFile4
PresentationConfigPresentationConfigFile5
AttributeProviderAttributeProviderConfigFile1
WebhookEndpointWebhookEndpointConfigFile1
TrustListTrustListConfigFile2
FederationTrustAnchorFederationTrustAnchorConfigFile1
StatusListStatusListConfigFile1

IssuanceConfig v2 and PresentationConfig v2 and v3 were introduced with EUDIPLO 9.0; 8.x cannot read them:

  • IssuanceConfig v2 adds the optional offerLifetimeSeconds. A v1 document is migrated unchanged.
  • PresentationConfig v2 replaces registration_cert.body.provided_attestations with the registrar's provides_attestations (a list of credential type identifiers). The migration removes provided_attestations with the warning PROVIDED_ATTESTATIONS_REMOVED; set provides_attestations yourself.
  • PresentationConfig v3 accepts integer and boolean DCQL claim values besides strings and requires them to be non-empty. A v2 document is migrated unchanged; an empty values array stops the migration with a validation error.

IssuanceConfig v3 came after 9.0. It adds the optional verifierKeyPem (PEM public key of the list signer) to walletProviderTrustLists entries. A v2 document is migrated unchanged; releases that only know v2, such as 9.0, cannot read v3 files.

TrustList v2 came with EUDIPLO 10.0. Entity info follows ETSI TS 119 602: country and lang codes, an absolute uri, and the required e-mail address (contactUri) and web site (website), with an optional phone (Trust lists). v1 has no website, so the v1 step only reports: it stops with the required input TRUST_LIST_WEBSITE_MISSING at /spec/entities/<index>/info/website and names the other values to change; rewrite the file as v2. 9.x cannot read v2 files.

PresentationConfig v4 came with EUDIPLO 10.0. It adds the optional allowedOrigins, the web origins that may request the presentation over the Digital Credentials API (Allowed origins), and format, signingCertificates and schemeTerritories in etsi_tl values for ETSI TS 119 612 Trusted Lists (Trusted Lists for QEAAs). A v3 document is migrated unchanged, and a bare presentation file with allowedOrigins, or with an etsi_tl value that has format, is read as v4. 9.x cannot read v4 files.

PresentationConfig v5 came with EUDIPLO 10.0. registration_cert holds the certificate (jwt) and the purpose and privacy_policy it is requested with (Registration Certificates); id, body and the flat registrationCert* form fields are removed. The v4 to v5 step moves body.purpose and body.privacy_policy up a level (from the form fields when no registration_cert is set), drops id and the other body fields with the warning REGISTRATION_CERT_FIELD_REMOVED, drops purposes without language or text with REGISTRATION_CERT_PURPOSE_INCOMPLETE, and warns with REGISTRATION_CERT_NOT_REQUESTED when the certificate was requested from the registrar and no jwt is set. A bare presentation file with registration_cert.purpose or .privacy_policy is read as v5. 9.x cannot read v5 files.

IssuanceConfig v4 came with EUDIPLO 10.0. It adds the optional walletAttestationStatusCheckMode (strict, best_effort or disabled) to the issuance configuration and its built-in, chained and oid4vp authorization servers. A v3 document is migrated unchanged; 9.x cannot read v4 files.

IssuanceConfig v5 came with EUDIPLO 10.0. It adds the optional federation fields for the published entity configuration (entityTypes, authorityHints, entityKeyChainId, entityConfigurationLifetimeSeconds, trustMarks, entityMetadata, includeTrustChain) and requires a non-empty federation.entityId to be an https or http URL with a host and without query, fragment, credentials or whitespace, written as the URL it stands for. When the document is applied, the server refuses http unless OUTBOUND_URL_ALLOW_HTTP=true (OpenID Federation). A v4 document with a valid or empty entityId is migrated unchanged. Another value stops the migration with the required input FEDERATION_ENTITY_ID_INVALID at /spec/federation/entityId; the value is not rewritten, and nothing is written until you set it.

IssuanceConfig v6 came with EUDIPLO 10.0. It removes the top-level signingKeyId, which only chose the key chain for the access tokens of the built-in authorization server. Access tokens are now signed only by key chains with usage type authorizationServer, which no earlier key chain has (Authorization server key chain). The v5 to v6 step therefore drops a set value with the warning ISSUANCE_SIGNING_KEY_ID_REMOVED instead of moving it; the built-in authorization server then uses the tenant's authorization server key chain. To choose one, set token.signingKeyId of its entry. A token.signingKeyId of an authorization server stays and gets the warning AUTHORIZATION_SERVER_KEY_CHAIN_REQUIRED at its path: from v6 on it must name a key chain with usage type authorizationServer, else the plan reports KEY_CHAIN_USAGE_MISMATCH, as a warning when the stored configuration already has the value. A document without either field is migrated unchanged; 9.x cannot read v6 files.

IssuanceConfig v7 came with EUDIPLO 10.0. registrationCertificate.mode and .renewal are removed: the issuer metadata carries the configured jwt only (Registration Certificates). The v6 to v7 step drops both. In generate mode, which was the default, a jwt was not served; the step drops it too, with the warning ISSUER_REGISTRATION_CERTIFICATE_JWT_DROPPED, so that it does not start to be published. An enabled certificate in generate mode then without jwt gets the warning ISSUER_REGISTRATION_CERTIFICATE_NOT_GENERATED. 9.x cannot read v7 files.

CredentialConfig v2 came with EUDIPLO 10.0. It accepts x509 as frameworkType of schemaMeta.trustedAuthorities entries, with the root certificate in value. A v1 document is migrated unchanged; 9.x cannot read v2 files.

CredentialConfig v3 came with EUDIPLO 10.0 as well. Claim field constraints, also those of children, accept only JSON Schema validation and annotation keywords (Constraints). The v2 to v3 step removes every other key, also inside subschemas, and subschema keywords whose value is not an object or boolean, each with the warning CLAIM_CONSTRAINT_KEYWORD_REMOVED at its path, for example /spec/fields/0/constraints/widget. v3 also matches claim patterns with RE2 (Constraints): a pattern or patternProperties key RE2 cannot run stops the migration with the required input CLAIM_PATTERN_UNSUPPORTED at its path, for example /spec/fields/0/constraints/pattern; the pattern is not rewritten, and nothing is written until you change it.

CredentialConfig v4 came with EUDIPLO 10.0 as well. config.display[] colors must be CSS Color Level 3 numerical values (#rgb, #rrggbb, lowercase rgb(), rgba(), hsl() or hsla() with comma-separated values, or transparent), and each locale may appear once, compared case-insensitively. The v3 to v4 step trims colors and lowercases their function names, removes an empty color, and removes any other color with the warning DISPLAY_COLOR_REMOVED at its path, for example /spec/config/display/0/text_color, so wallets use their own. A second entry for one locale stops the migration with the required input DISPLAY_LOCALE_DUPLICATE at /spec/config/display/<index>/locale, and nothing is written until you remove or change it. 9.x cannot read v4 files.

KeyChain v2 came with EUDIPLO 10.0. It adds the optional type (standalone or internalChain), which exports write. For a private-jwk key source without activeJwk it says whether jwk is the signing key or a CA key under which the import creates a new signing key, as type does for POST /api/key-chain/import. For regenerate it is the type of the new key chain, like keySource.keyChainType; without either, a document with activeCertificate becomes an internal chain. For the other key sources, and for a regenerate key source with both, it must match the key chain they describe, or the plan reports KEY_CHAIN_TYPE_MISMATCH. A v1 document is migrated unchanged; 9.x cannot read v2 files. A bare key chain file with type, as GET /api/key-chain/{id}/export writes it, is read as v2.

KeyChain v4 came with EUDIPLO 10.0. It adds the usage type authorizationServer for the key chains that sign access tokens (Authorization server key chain). A v3 document is migrated unchanged; a bare key chain file with usage type authorizationServer is read as v4.

KeyChainDefaults v1 came with EUDIPLO 10.0. The singleton KeyChainDefaults/defaults (key-chain-defaults.json) holds the tenant's key chain per usage type, used where no configuration names one. v1 has one entry, access: the default access key chain. The document replaces all entries, so leaving access out of a document that is applied removes it, and the tenant picks its access key chain by rule again. The plan reports MISSING_RESOURCE_REFERENCE when an entry names a key chain that is neither stored nor in the bundle, and KEY_CHAIN_USAGE_MISMATCH when the key chain's usage type is not the entry's. An export writes the document only while an entry is set.

KeyChainDefaults v2 came with EUDIPLO 10.0 as well. It adds the optional entry authorizationServer: the key chain with usage type authorizationServer that signs the access tokens of authorization servers without token.signingKeyId (Authorization server key chain). A v1 document is migrated unchanged; a bare key-chain-defaults.json with authorizationServer is read as v2.

Tenant v4 came with EUDIPLO 10.0 as well. Tenant v2 and v3, which only development builds of 10.0 wrote, kept the default key chains in info.json (defaultAccessKeyChainId, then defaultKeyChains); v4 moves them to KeyChainDefaults. The upgrade to v4 drops the field with the warning DEFAULT_KEY_CHAINS_MOVED and does not apply it; move the value to key-chain-defaults.json. A v1 document is migrated unchanged. A bare info.json with defaultKeyChains is read as v3, one with defaultAccessKeyChainId as v2. 9.x cannot read v2 to v4 files.

Client v2 came with EUDIPLO 10.0 as well. It accepts the roles audit:read, sessions:read, credentials:status and keys:manage. A v1 document is migrated unchanged; 9.x cannot read v2 files.

KmsConfig v2 came with EUDIPLO 10.0 as well. It adds the optional algorithms and defaultAlgorithm of a provider, which limit the signing algorithms of new and imported key chains, including KeyChain documents of a bundle. A bare kms.json with algorithms or defaultAlgorithm on a provider is read as v2. A v1 document is migrated unchanged; 9.x cannot read v2 files.

RegistrarConfig was removed in EUDIPLO 10.0 together with the sandbox registrar integration. A registrar.json in a tenant folder and a RegistrarConfig document in a bundle are skipped with the warning REGISTRAR_CONFIG_REMOVED; the rest of the import goes on. eudiplo config upgrade leaves registrar.json out of the upgraded folder with a warning; run on a single RegistrarConfig document, it fails with the same message, as there is no current version to upgrade it to.

Tenant folder layout​

Startup import reads CONFIG_FOLDER (/app/config/config in the image). Every directory in it, including symlinked ones, is a tenant folder, except one whose name contains \ or is kms.json, which is skipped with a warning; a tenant that does not exist yet is created only if its folder contains info.json.

<CONFIG_FOLDER>/
├── kms.json global KMS providers
└── <tenant-id>/
├── info.json Tenant (name, description, session and status-list defaults)
├── kms.json tenant KMS providers, merged over the global file
├── key-chain-defaults.json KeyChainDefaults (default key chains: access, authorizationServer)
├── clients/<id>.json
├── key-chains/<id>.json
├── attribute-providers/<id>.json
├── webhook-endpoints/<id>.json
├── trust-lists/<id>.json
├── federation-trust-anchors/<id>.json
├── issuance/
│ ├── issuance.json IssuanceConfig
│ ├── credentials/<id>.json
│ └── status-lists/<id>.json
├── presentation/<id>.json
└── images/<file> logos and credential images, referenced by file name

File names are not significant; the ID comes from the document. In images/, the files .gitkeep, .DS_Store, Thumbs.db and desktop.ini are not imported; every other file is an image.

Bundle layout​

An export is a ZIP archive or the same content as one JSON object ({ "manifest": …, "documents": [ … ], "assets": [ … ] }, assets base64-encoded). The ZIP uses the folder layout above for one tenant, with two differences: the files sit at the root of the archive, and the issuance settings are stored as issuance/config.json.

manifest.json contains:

FieldContent
formateudiplo.config-bundle
formatVersion2 for new bundles; version 1 bundles are still read
sourceVersion, exportedAt, tenantOrigin of the export
resources[]kind, id, $schema, path, sha256, ownership, generation per document
assets[]path, contentType, sha256 per binary file
requirements[]Values the target must supply: code, resource, path, message, placeholder
warnings[]Warnings of the export: migration warnings, and CLIENT_MANAGED_BY_IDENTITY_PROVIDER for each client record left out (see below)

Integrity and limits. Backend and CLI verify that resource identities, paths and SHA-256 checksums match the manifest. Duplicate resources, unsafe paths and ZIP entries not listed in the manifest are rejected. A ZIP may have at most 50 MiB compressed, 100 MiB expanded and 10,000 entries.

Secret and key policy​

Bundle exports (GET /api/config-bundles/export) never contain secret values or database-held private keys. The document of a single key chain is the one exception (single resources).

ValueIn the exportRequirement codeOn import
Retrievable secrets (KMS, webhook and attribute-provider credentials, upstream client secrets of chained authorization servers)${…} placeholderSECRET_REQUIREDSet the environment variable or replace the value
Client secrets (stored as bcrypt hash)${…} placeholderCLIENT_SECRET_REQUIREDSupply a secret, or "secret": "!generate" to get a new one once in generatedSecrets
Private keys of db key chainskeySource: { "type": "required", "publicJwk": … }PRIVATE_KEY_REQUIREDSupply private-jwk, or { "type": "regenerate" } for new key material
Keys in an external KMSkeySource: { "type": "external-reference", provider, externalKeyId, publicJwk }-The target provider must reach the same key; checked by signing a challenge
Sessions, status values, cachesnot exported--

A secret that is not set, such as the API key of a webhook endpoint without authentication, is left out of the export and adds no requirement. Exception: with Keycloak (OIDC set and OIDC_PROVIDER unset or keycloak), Keycloak holds the client secrets, so every client gets the placeholder and CLIENT_SECRET_REQUIRED.

regenerate keeps the key chain ID but creates a new cryptographic identity: certificates and anything bound to the old key must be renewed. In upsert and replace mode it does so again whenever the document changed (which documents count as unchanged).

A private-jwk key source takes one of two forms:

  • With only jwk, the document is imported like POST /api/key-chain/import and accepts only that request's fields; the plan blocks the resource when d is missing or does not belong to x and y. To restore an exported internal chain, put its root CA key from GET /api/key-chain/{id}/export into jwk, remove activeCertificate and keep "type": "internalChain": EUDIPLO keeps the root CA certificate and creates a new signing key under it. Without type and rotation, the root CA key itself becomes the signing key.
  • With activeJwk as well, it stores an internal chain as given, in the database: jwk is the root CA key and crt holds exactly its certificate, activeJwk is the signing key and activeCertificate its certificate, which may be followed by the root certificate. Both certificates must be PEM and match their keys, the root certificate must be a CA certificate, and kmsProvider must be db or left out; the plan blocks the resource otherwise. Bundle exports and GET /api/key-chain/{id}/export never contain the signing key of an internal chain (key chain export); GET /api/config-bundles/resources/KeyChain/{id}/document writes this form (single resources).

Placeholders. Any string value can be ${VAR} or ${VAR:default} (uppercase letters, digits, _; an empty variable counts as unset). Values are substituted once and not interpreted again. In tenant folders, unresolved placeholders are handled according to CONFIG_VARIABLE_STRICT:

ValueEffect
skip (default), abort, trueError; the import of this tenant fails, other tenants continue
ignore, falseWarning; the placeholder stays as literal text

Import modes and plan actions​

ModeExisting resourceResource missing from the bundle
createskip (warning RESOURCE_EXISTS)kept
upsertupdate or unchangedkept
replaceupdate or unchangeddelete, only if it was imported earlier from the same source
Plan actionMeaning
createThe resource will be created
updateThe resource will change; the plan lists its field changes, secrets redacted
unchangedAlready matches, or a key chain or !generate client document this source already applied (see below); only ownership metadata may be updated
skipExists and is left alone: in create mode (RESOURCE_EXISTS), in a startup import when the resource was detached from that folder (RESOURCE_DETACHED) or has a newer stored generation (STALE_GENERATION), or because it is the tenant's encryption key chain (KEY_CHAIN_ID_RESERVED), or a client record that replace keeps with OIDC_PROVIDER=generic (CLIENT_MANAGED_BY_IDENTITY_PROVIDER, see below)
deleteWill be removed (replace mode)
blockedCannot be applied, for example STALE_GENERATION, MISSING_RESOURCE_REFERENCE, STATUS_LIST_LAYOUT_IMMUTABLE, REGISTRATION_CERTIFICATE_REFUSED for an imported registration certificate that fails its checks, for example because it is expired or does not cover the DCQL query (Validation), a missing secret or key, UNSUPPORTED_KEY_ALGORITHM for a key chain whose key uses an algorithm its KMS provider does not offer (Signing algorithms), KMS_CONFIG_FOLDER_MISSING on a KmsConfig document for a tenant whose ID is no folder name (Per-tenant providers), CLIENT_MANAGED_BY_IDENTITY_PROVIDER on a Client document with OIDC_PROVIDER=generic (see below), TRUST_LIST_IN_USE on a trust list that replace would delete while a configuration still references it (Delete a trust list), MISSING_RESOURCE_REFERENCE on a presentation configuration that names, or the issuance configuration that adds, an OpenID Federation trust anchor neither the tenant nor the bundle registers, FEDERATION_TRUST_ANCHOR_IN_USE on a trust anchor that the import would delete or give another entity ID while a configuration still names it (Delete a trust anchor), KEY_CHAIN_IN_USE on a key chain that replace would delete while a configuration still names it (Delete a key chain), or KEY_CHAIN_USAGE_MISMATCH on the key chain defaults (KeyChainDefaults) when an entry names a key chain of another usage type (Default access key chain), on the issuance configuration when a token.signingKeyId it sets names no authorizationServer key chain (Authorization server key chain), or on a trust list when an internal entity names a key chain of another usage type in issuerKeyChainId or revocationKeyChainId that the stored list does not already name there and the import does not skip the list, or when the key chain that signs a list the import writes, in keyChainId or kept from the stored list, has no usage type trustList (Trust lists). KEY_CHAIN_USAGE_MISMATCH takes the usage type from a KeyChain document of the bundle that the import writes, else from the stored key chain; a KeyChain document the plan skips does not count. One blocked item blocks the whole plan

An update item lists its field changes in changes: the path in the document, the stored value as before and the value after the import as after. Without before, the import adds the field; without after, it removes the stored value. Entries with redacted: true hide the values: a secret reads [redacted], and a value that changes between an object, a list and a plain value reads [changed] on both sides.

A KmsConfig or KeyChainDefaults document replaces the stored resource: fields it leaves out are removed, and the plan lists their removal. A KeyChain document replaces the stored key material, and also the type, description and rotation policy:

  • The plan lists type as the import creates it, also for a document without type (KeyChain v2).
  • A description it leaves out is removed.
  • Without rotationPolicy, rotation is disabled.
  • A rotation value it leaves out or sets to null is not set. Exception: a private-jwk key source without activeJwk is imported like POST /api/key-chain/import, so with rotation enabled a missing intervalDays becomes 90 and a missing certValidityDays 365, and with rotation disabled no intervals are stored.

The plan lists these values as they will be stored. For the other kinds, a top-level field the document leaves out keeps its stored value.

A KeyChain document that is identical to the one last applied from the same source (the same config folder, or bundles whose manifest names the same tenant) plans unchanged while the key chain is file-managed, without comparing it with the stored key chain: importers add key IDs, EUDIPLO creates the signing key of a CA key, and rotation or a certificate from a registrar replace keys and certificates later. These changes stay, so certificates EUDIPLO created during the import are only renewed by rotation. A document applied under an earlier format version, for example a KeyChain v1 file that 9.x applied, is still identical when its migration to the current format changes only $schema; a migration that rewrites spec or metadata makes it a changed document. Reattaching always applies the folder version. To apply an unchanged document again, for example to regenerate a key, raise metadata.generation; in a bundle, also update the document's sha256 in manifest.json.

The same rule covers a Client document with "secret": "!generate", since applying it generates a new secret: once this source applied it, the client keeps its secret while the document stays the same. A changed document, a raised metadata.generation, another source or reattaching generates a new secret, returned once in generatedSecrets. Other Client documents are compared field by field. With Keycloak (OIDC set and OIDC_PROVIDER unset or keycloak), every Client document is applied on every import, because the plan cannot see changes made in Keycloak; a !generate client applied as it is keeps its secret.

The tenant's encryption key chain is managed by EUDIPLO and is not configuration: exports leave it out, and plans neither change nor delete it. A KeyChain document with its ID, such as the one exports of earlier versions contain, is skipped (warning KEY_CHAIN_ID_RESERVED).

The import pipeline is: decode, verify checksums, migrate to the current versions, validate, check references and external keys, plan, apply in dependency order (for example key chains before issuance configs), record file-managed ownership. Applying needs the planFingerprint of the reviewed plan; a changed bundle, mode or target state fails with CONFIG_PLAN_STALE. Status lists keep their capacity and bit size: import a new list ID for a different layout.

Clients with another identity provider​

With OIDC_PROVIDER=generic, the identity provider manages the clients, so bundles and config folders carry none:

  • An export leaves clients out and adds the warning CLIENT_MANAGED_BY_IDENTITY_PROVIDER for each client record left from an earlier mode. GET /api/config-bundles/resources/Client/:id/document answers 501.
  • A Client document blocks the plan with CLIENT_MANAGED_BY_IDENTITY_PROVIDER. In a config folder, a file under clients/ fails the import of its tenant until you delete it; create the client in the identity provider instead.
  • replace keeps a client record that its source no longer has: the plan lists it as skip with the warning CLIENT_MANAGED_BY_IDENTITY_PROVIDER. Such a record only adds limits to the tokens of its client (External OIDC provider).

Management API​

All endpoints act on the tenant of the access token and accept tenant:admin or tenants:manage (roles), except where noted below.

EndpointPurpose
GET /api/config-bundles/export?format=zip|jsonExport the tenant (default json)
POST /api/config-bundles/plan?mode=…Plan a JSON bundle
POST /api/config-bundles/plan/archive?mode=…Plan a ZIP bundle (multipart field bundle)
POST /api/config-bundles/import?mode=…&planFingerprint=…Apply a JSON bundle; replace also needs confirmReplace=true
POST /api/config-bundles/import/archive?mode=…&planFingerprint=…Apply a ZIP bundle; replace also needs confirmReplace=true
POST /api/config-bundles/documents/upgradeUpgrade one document to the current version
GET /api/config-bundles/operations, GET …/operations/:idLatest 50 operation reports, or one report
POST /api/config-bundles/operations/:id/acknowledge-interruption?confirmWorkerStopped=trueRelease the lock of an interrupted operation
GET /api/config-bundles/resourcesOwnership and generation of every resource
GET /api/config-bundles/resources/:kindOwnership and generation of one kind's resources
GET /api/config-bundles/resources/:kind/:id/documentExport one resource as a document (single resources)
POST /api/config-bundles/resources/:kind/:id/detachMake a file-managed resource detached
POST /api/config-bundles/resources/:kind/:id/reattach/planPlan resetting a resource to its version in CONFIG_FOLDER
POST /api/config-bundles/resources/:kind/:id/reattach?planFingerprint=…Apply that plan and make the resource file-managed again

Exports of bundles and single resources, imports, detach and reattach actions are recorded in the tenant audit log.

GET /api/config-bundles/resources/:kind also accepts the roles that change resources of that kind, so screens can lock file-managed resources for them:

KindAlso readable with
Tenant (session and status list settings)issuance:manage, presentation:manage
KeyChain, KeyChainDefaults (default key chains)issuance:manage, presentation:manage, keys:manage
WebhookEndpoint, TrustList, FederationTrustAnchorissuance:manage, presentation:manage
IssuanceConfig, CredentialConfig, AttributeProvider, StatusListissuance:manage
PresentationConfigpresentation:manage
Clientclients:manage
KmsConfigno other role

Single resources​

GET /api/config-bundles/resources/:kind/:id/document returns one resource as a document in the current format version: the content of its file in a tenant folder or a bundle. Save it as <directory>/<id>.json (for the singletons info.json, kms.json, key-chain-defaults.json and issuance/issuance.json) and, once its ${…} placeholders are set, the next import plans it as unchanged. The singletons use their fixed IDs tenant, kms, defaults and issuance; the tenant's encryption key chain is not configuration and answers 404. The Download configuration buttons of the Web Client save this document as <id>.json, and the import of Settings > Config Portability accepts it in place of a bundle.

Secrets are ${…} placeholders as in a bundle export (secret and key policy); with the default CONFIG_VARIABLE_STRICT=skip, a folder import fails for that tenant until the environment variables are set. The Web Client names them after the download. Image references name the file, which has to be in the folder's images/ or already stored on the target instance. Unlike a bundle, a KeyChain document of a key held in the database keeps its private keys as keySource: { "type": "private-jwk" }, for an internal chain with the signing key in activeJwk, so its import restores the same keys. A KeyChain document therefore needs tenant:admin or tenants:manage; the other kinds also accept the roles in the table above.