#Local Development

To run the enterprise stack locally, you need Docker (v20.10.14) and a MongoDB database. Below, you find instructions on how to:

use our quickstart repo to spin up the Enterprise API next to a local MongoDB database using docker-compose.
run the Enterprise API without the local MongoDB. This setup can be useful if you want to connect to a custom MongoDB instance.

#Quickstart

Clone the enterprise quickstart repository

git clone https://github.com/walt-id/waltid-enterprise-quickstart.git

$ docker login -u waltid

At the password prompt, enter the personal access token you received from us.
Start docker-compose

docker-compose up

Once docker-compose is running, you can visit enterprise.localhost:3000/swagger to access the Enterprise APIs.

#Next Steps

Enterprise Foundations - Learn more about the Enterprise Stack core building blocks
Administration - Learn about organizations, tenants, and the details of authentication and access management.
Services - Explore various services (e.g., issuer, verifier) and their detailed usage.

#Running Enterprise API (without MongoDB)

Pulling the Enterprise API Docker Image

$ docker login -u waltid

At the password prompt, enter the personal access token you received from us.
Pull the image

docker pull waltid/waltid-enterprise-api:{version}

Running The Image

Configuration Files

Please prepare all the configuration files required to start the enterprise stack in a folder called config . You can use the config folder in our waltid-enterprise-quickstart repo as a reference.

The folder should include the following files:

_features.conf
auth.conf
database.conf
enterprise.conf
superadmin-registration.conf
web.conf

You can learn more about each of them in the configuration section.

Running the image

With the command below, we start the enterprise stack API, mount the folder with all the required configuration files into it, and make the API accessible via localhost:3000

docker run -p 3000:3000 -it -v $(pwd)/config: /config -t waltid/waltid-enterprise-api: 0.1.0

Using host aliases

Sometimes you may want to use a custom domain for your enterprise stack. You can do this by adding a host alias to the enterprise stack. Use cases include:

Testing local issuance and verification flows against remote wallets (e.g. EUDI wallet)
External DID Web Hosting. See more here: External DID Web Hosting

To add a host alias, you can use the following command:

curl -X 'POST' \
  'https://{orgID}.enterprise.cloud/v1/{target}/host-alias-api/host-aliases/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "domain": "your-custom-domain.com"
}'

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 waltid, your default Base URL will be waltid.enterprise.cloud.
target: resourceIdentifier - The target indicates the tenant for which to create the host alias ({organizationID}.{tenantID}.{host_alias_id}), e.g. waltid.tenant.my_alias`

Body Parameters

domain: String - The custom domain that you want to use for your tenant.

#Issuer Service Configuration

When configuring the issuer service, you need to use the host alias in the baseUrl parameter.

{
  "baseUrl": "https://your-custom-domain.com"
}

#Verifier Service Configuration

When configuring the verifier service, you need to use the host alias in the baseUrl parameter.

{
  "baseUrl": "https://your-custom-domain.com"
}

#Verifier2 Service Configuration

When configuring the verifier2 service, you need to use the host alias in the url_host parameter when creating the verifier2 service or creating new verification sessions.

{
  "url_config": {
        "url_prefix": "https://your-custom-domain.com/v1/{target}/verifier2-service-api",
        "url_host": "haip-vp://authorize"
    },
}

Where {target} is the resource identifier target of the verifier2 service you are using.

Last updated on February 3, 2026

Setup Administration