--- title: "Setup" description: "There are two ways to set up a new wallet (wallet-service):" stack: "Enterprise Stack (commercial) — version 0.21.0" stack_version: "0.21.0" stack_comparison: https://docs.walt.id/community-vs-enterprise.md canonical_url: https://docs.walt.id/enterprise-stack/services/wallet-service/setup generated: 2026-07-20 --- # Setup **There are two ways to set up a new wallet (wallet-service):** - [**Wizard-based setup**](#creating-a-wallet-with-dependencies-wizard): Use the Wallet Service wizard to automatically create a wallet instance and configure the necessary dependency services (e.g., KMS, DID Store, Credential Store). This setup not only enables core wallet functionality—such as receiving and sharing credentials—but also ensures that credentials, keys, and DIDs are associated and stored for the wallet. - [**Manual setup**](#creating-a-wallet-without-dependencies): Create a standalone wallet service without any dependency services to enable core wallet functionality, such as receiving credentials via OID4VC and presenting them via OID4VP. Optionally, you can provide a static key and DID to associate with the wallet — ideal if the wallet only needs to have a single key and DID. With that there is no requirement for a DID store or KMS. If needed, you can also manually attach services like KMS, DID service, DID store, or a credential store to support multiple keys and DIDs, and to persist (store) received credentials. **Note:** Each Wallet Service instance corresponds to a single wallet identified by a unique ID, known as a **target** ( e.g., `waltid.tenant1.wallet1`). ## Creating a Wallet with Dependencies (Wizard)
**The Role of Dependency Services** Dependency services ensure that the wallet goes beyond basic, stateless functionality—such as receiving credentials via OID4VC without storing them, or presenting credentials via OID4VP by supplying the raw credential instead of a stored reference. These services provide the necessary infrastructure for persistence and full-featured wallet capabilities: - [**KMS Service**](https://docs.walt.id/enterprise-stack/services/key-management-service/overview.md) – Provides the wallet with keys needed to receive credentials and to sign credential presentations. - [**DID Service**](https://docs.walt.id/enterprise-stack/services/did-service/overview.md) – Enables the wallet to create one or more decentralized identifiers (DIDs). - [**DID Store**](https://docs.walt.id/enterprise-stack/services/did-store-service/overview.md) – Persists the DID Documents of the created DIDs. - [**Credential Store**](https://docs.walt.id/enterprise-stack/services/credential-store-service/overview.md) – Stores received credentials so they can be viewed, managed, and later retrieved for presentation. - [**Client Attestation Service**](https://docs.walt.id/enterprise-stack/services/client-attestation-service/overview.md) _(optional)_ – Enables the wallet to authenticate itself when an issuer’s authorization server metadata lists `attest_jwt_client_auth` (issuer `clientAuthenticationConfig` includes `client-attestation`). See [wallet integration](https://docs.walt.id/enterprise-stack/services/client-attestation-service/wallet-integration.md). ### Create New Service Dependencies In this example, we will create a wallet and initialize all dependency services like KMS, DID Service, DID Store Service, and Credential Store Service. If you already have created some of these services, please refer to the [Link Existing Service Dependencies Example](#link-existing-service-dependencies). **Option: CURL** Endpoint: `/v1/{target}/wallet-service-api/init-wallet` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Service%20%7C%20Wallet%20Service/post_v1__target__wallet_service_api_init_wallet) **Example Request** ```bash curl -X 'POST' \ 'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/wallet-service-api/init-wallet' \ -H 'accept: */*' \ -H 'Authorization: Bearer {yourToken}' \ -H 'Content-Type: application/json' \ -d '{ "createKms": true, "kmsName": "my-custom-kms-name", "createKeyInKms": { "backend": "jwk", "keyType": "Ed25519" }, "createDidStore": true, "didStoreName": "my-custom-did-store-name", "createDidService": true, "didServiceName": "my-custom-did-service-name", "createDidWithDidService": "jwk", "createCredentialStore": true, "credentialStoreName": "my-custom-credential-store-name" }' ``` **Body** ```json { "createKms": true, "kmsName": "my-custom-kms-name", "createKeyInKms": { "backend": "jwk", "keyType": "Ed25519" }, "createDidStore": true, "didStoreName": "my-custom-did-store-name", "createDidService": true, "didServiceName": "my-custom-did-service-name", "createDidWithDidService": "jwk", "createCredentialStore": true, "credentialStoreName": "my-custom-credential-store-name" } ``` **Path Parameters** - `orgID`: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named `test`, your default Base URL will be `test.enterprise-sandbox.walt.dev` when using the sandbox environment. - `target`: _resourceIdentifier_ - The target indicates the organization + tenant in which to create the new wallet ( wallet service) and the wallet's ID (`{organizationID}.{tenantID}.[walletID]`), e.g. `waltid.tenant1.wallet1` **Body Parameters** - `createKms` _Boolean_ - Specifies whether a new [KMS service](https://docs.walt.id/enterprise-stack/services/key-management-service/overview.md) should be created. - `kmsName` (optional) _String_ - Custom name for the KMS service. This will be the last part of the resource ID. For example, `waltid.tenant1.{kms-name}`. - `createKeyInKms` (optional) _Object_ - Object defining the key to create in the KMS. It follows the same structure as the create key request in the KMS service. Learn more about the different options [here](https://docs.walt.id/enterprise-stack/services/key-management-service/local.md). - `createDidStore` _Boolean_ - Indicates whether a [DID Store Service](https://docs.walt.id/enterprise-stack/services/did-store-service/overview.md) should be created. - `didStoreName` (optional) _String_ - Custom name for the DID Store Service. This will form part of the resource ID. For example, `waltid.tenant1.{did-store-name}`. - `createDidService` _Boolean_ - Specifies if a [DID Service](https://docs.walt.id/enterprise-stack/services/did-service/overview.md) should be created. - `didServiceName` (optional) _String_ - Custom name for the DID Service. This will be included in the resource ID. For example, `waltid.tenant1.{did-service-name}`. - `createDidWithDidService` (optional) _String_ - Method for creating a DID in the DID Service. Supported values: `jwk` or`key` - `createCredentialStore` _Boolean_ - Indicates whether a [Credential Store Service](https://docs.walt.id/enterprise-stack/services/credential-store-service/overview.md) should be created. - `credentialStoreName` (optional) _String_ - Custom name for the Credential Store Service. This will be part of the resource ID. For example, `waltid.tenant1.{credential-store-name}`. --- **Response Codes** - `201` - Wallet created successfully. **Body** ```json { "wallet": { "dependencies": [ "waltid.usertenant.didstore", "waltid.usertenant.kms", "waltid.usertenant.credentialstore" ], "traversable": true, "_id": "waltid.usertenant.wallet3", "configuration": {}, "parent": "waltid.usertenant" }, "createdResources": { "keyId": "waltid.usertenant.kms.wallet_key", "didId": "waltid.usertenant.didstore.wallet_did", "did": "did:key:zDnaeSwMcFNobzqVhKxAGRrZAct37L4o7fMzQXocuKDASmiq3" } } ``` ### Link Existing Service Dependencies In this example, we will create a wallet and link existing dependency services like KMS, DID Service, DID Store Service, and Credential Store Service. **Option: CURL** Endpoint: `/v1/{target}/wallet-service-api/init-wallet` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Service%20%7C%20Wallet%20Service/post_v1__target__wallet_service_api_init_wallet) **Example Request** ```bash curl -X 'POST' \ 'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/wallet-service-api/init-wallet' \ -H 'accept: */*' \ -H 'Authorization: Bearer {yourToken}' \ -H 'Content-Type: application/json' \ -d '{ "kms": "waltid.tenant1.my-custom-kms-name-test-1", "createKms": false, "didStore": "waltid.tenant1.my-custom-did-store-name-test-1", "createDidStore": false, "didService": "waltid.tenant1.my-custom-did-service-name-test-1", "createDidService": false, "credentialStore": "waltid.tenant1.my-custom-credential-store-name-test-1", "createCredentialStore": false }' ``` **Body** ```json { "kms": "waltid.tenant1.my-custom-kms-name-test-1", "createKms": false, "didStore": "waltid.tenant1.my-custom-did-store-name-test-1", "createDidStore": false, "didService": "waltid.tenant1.my-custom-did-service-name-test-1", "createDidService": false, "credentialStore": "waltid.tenant1.my-custom-credential-store-name-test-1", "createCredentialStore": false } ``` **Path Parameters** - `orgID`: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named `test`, your default Base URL will be `test.enterprise-sandbox.walt.dev` when using the sandbox environment. - `target`: _resourceIdentifier_ - The target indicates the organization + tenant in which to create the new wallet ( wallet service) and the wallet's ID (`{organizationID}.{tenantID}.[walletID]`), e.g. `waltid.tenant1.wallet1` **Body Parameters** - `kms` _Target_ - Resource ID (target) of the KMS to link to the wallet, e.g. `waltid.tenant1.kms1`. - `createKms` _Boolean_ - Specifies whether a new [KMS service](https://docs.walt.id/enterprise-stack/services/key-management-service/overview.md) should be created. - `didStore` _Target_ - Resource ID (target) of the DID Store to link to the wallet, e.g. `waltid.tenant1.did-store1`. - `createDidStore` _Boolean_ - Indicates whether a [DID Store Service](https://docs.walt.id/enterprise-stack/services/did-store-service/overview.md) should be created. - `didService` _Target_ - Resource ID (target) of the DID Service to link to the wallet, e.g. `waltid.tenant1.did-service1`. - `createDidService` _Boolean_ - Specifies if a [DID Service](https://docs.walt.id/enterprise-stack/services/did-service/overview.md) should be created. - `credentialStore` _Target_ - Resource ID (target) of the Credential Store Service to link to the wallet, e.g. `waltid.tenant1.credential-store1`. - `createCredentialStore` _Boolean_ - Indicates whether a [Credential Store Service](https://docs.walt.id/enterprise-stack/services/credential-store-service/overview.md) should be created. resource ID. For example, `waltid.tenant1.{credential-store-name}`. --- **Response Codes** - `201` - Wallet created successfully. **Body** ```json { "wallet": { "dependencies": [ "waltid.usertenant.didstore", "waltid.usertenant.kms", "waltid.usertenant.credentialstore" ], "traversable": true, "_id": "waltid.usertenant.wallet3", "configuration": {}, "parent": "waltid.usertenant" }, "createdResources": { } } ``` - `401` - Invalid authentication ## Creating a Wallet without Dependencies In this example, we will create a wallet without any dependency services (KMS, DID service, DID Store, Credential Store). Optionally, we can provide a static key and DID to be associated with the wallet. With this setup (with static key and DID), the wallet is still capable of receiving and presenting credentials. However, it will not store them, since no credential store is attached. Similarly, the DID document related to the static DID must be stored separately, as there is no DID store connected. Despite this minimal setup (static key and DID), it is still possible to manually attach other services like a credential store or DID store, as described in the [section below](#attach-service-dependencies-to-wallet-after-creation). **Option: CURL** Endpoint: `/v1/{target}/resource-api/services/create` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Service%20%2F%20Resource/post_v1__target__resource_api_services_create) **Example Request** ```bash curl -X 'POST' \ 'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \ -H 'accept: */*' \ -H 'Authorization: Bearer {yourToken}' \ -H 'Content-Type: application/json' \ -d '{ "type": "wallet", "configuration": { "staticKey": { "type": "jwk", "jwk": { "kty": "OKP", "d": "wZ69WYFIZHYEC9gWsRYCIHsJ4G5qdZeCrCry6szGij4", "crv": "Ed25519", "kid": "I-bh2IYP93feK_dIYA7QaNSHoRlftw53KYpNYPdEpNQ", "x": "sD8DqvgzEjQaex5p4NNp_Qyd8knJAJfZY7Ge8vCmBGY" } }, "staticDid": "did:key:z6MkrKFXimvdRgYnsFeyQq5sUn4vmXJVDHriHJKpgy6oaC6H" } }' ``` **Body** ```json { "type": "wallet", "configuration": { "staticKey": { "type": "jwk", "jwk": { "kty": "OKP", "d": "wZ69WYFIZHYEC9gWsRYCIHsJ4G5qdZeCrCry6szGij4", "crv": "Ed25519", "kid": "I-bh2IYP93feK_dIYA7QaNSHoRlftw53KYpNYPdEpNQ", "x": "sD8DqvgzEjQaex5p4NNp_Qyd8knJAJfZY7Ge8vCmBGY" } }, "staticDid": "did:key:z6MkrKFXimvdRgYnsFeyQq5sUn4vmXJVDHriHJKpgy6oaC6H" } } ``` **Path Parameters** - `orgID`: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named `test`, your default Base URL will be `test.enterprise-sandbox.walt.dev` when using the sandbox environment. - `target`: _resourceIdentifier_ - The target indicates the organization + tenant in which to create the new wallet ( wallet service) and the wallet's ID (`{organizationID}.{tenantID}.[walletID]`), e.g. `waltid.tenant1.wallet1` **Body Parameters** - `type` _serviceType_ - Specifies the type of service to create. In our case `wallet` - `configuration` (optional) _Object_ - Object to configure static key & DID. - `staticKey` _Key_ - A key object that specifies the key to be associated with the wallet. Its structure matches the format returned under the key property when creating a key using the [KMS service](https://docs.walt.id/enterprise-stack/services/key-management-service/overview.md). - `staticDid` _String_ - String of the DID to be associated with the wallet. --- **Response Codes** - `201` - Wallet created successfully. ## Attach Service Dependencies to Wallet After Creation In the example below, we will attach a credential store service to an existing wallet to ensure that received credentials are automatically stored. The same approach can be used to attach other services as needed, such as a KMS service, DID service, or DID store service. **Option: CURL** Endpoint: `/v1/{target}/wallet-service-api/dependencies/add` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Service%20%7C%20Wallet%20Service/post_v1__target__wallet_service_api_dependencies_add) **Example Request** ```bash curl -X 'POST' \ 'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/wallet-service-api/dependencies/add' \ -H 'accept: */*' \ -H 'Authorization: Bearer {yourToken}' \ -H 'Content-Type: application/json' \ -d 'waltid.tenant1.credential-store-1' ``` **Body** ``` waltid.tenant1.credential-store-1 ``` **Path Parameters** - `orgID`: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named `test`, your default Base URL will be `test.enterprise-sandbox.walt.dev` when using the sandbox environment. - `target`: _resourceIdentifier_ - The target indicates the organization + tenant + wallet service to which to add an existing Credential Store (`{organizationID}.{tenantID}.{walletServiceID}`), e.g. `waltid.tenant1.wallet1` **Body Parameters** - Specifies the ID of the Credential store that should be linked. --- **Response Codes** - `201` - Unit attached.