#Local Development

The Enterprise Stack requires a license from walt.id. See Licensing for how to configure license.conf and activate it.

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
license.conf
superadmin-registration.conf
web.conf

You can learn more about each of them in the configuration section. First startup also needs LICENSE_STATE_ENCRYPTION_KEY and a license seed — see Licensing.

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/v2/{target}/verifier-service-api",
        "url_host": "haip-vp://authorize"
    },
}

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

#Verify Image Signature and extract SBOM

Verify image signature

cosign verify \
  --certificate-identity-regexp 'https://github.com/walt-id/waltid-identity-enterprise/\.github/workflows/image-sign\.yml@refs/heads/main' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  waltid/waltid-enterprise-api:1.0.0

Inspect the image - This lists the platform-specific manifests (ARM/AMD).

docker buildx imagetools inspect docker.io/waltid/waltid-enterprise-api:1.0.0

Name:      docker.io/waltid/waltid-enterprise-api:1.0.0
MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest:    sha256:d3d6c118ba6514db41a73d984035560c5d0fa99e31171d11971cb1160da752ff
           
Manifests: 
  Name:      docker.io/waltid/waltid-enterprise-api:1.0.0@sha256:6b8159976b08ad00dafdef184eb9ab9b153766e4d214c8fe8653016a5ffa8e5a
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/amd64
             
  Name:      docker.io/waltid/waltid-enterprise-api:1.0.0@sha256:f4999c2fac609f64529ec23766bab0c5384ef1f131a21efc026b05a00db89e75
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/arm64

Use Cosign with the manifest digest to verify and extract the CycloneDX SBOM:

cosign verify-attestation --type cyclonedx \
  --certificate-identity "https://github.com/walt-id/waltid-identity-enterprise/.github/workflows/sbom-attest.yml@refs/heads/main" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  waltid/waltid-enterprise-api@sha256:6b8159976b08ad00dafdef184eb9ab9b153766e4d214c8fe8653016a5ffa8e5a \
  2>/dev/null | jq -r '.payload' | base64 -d | jq -r '.predicate' > api-sbom-amd.cdx.json

Last updated on August 26, 2026

Setup Licensing