Environment Variables

Copy .env.sample from the repository root to .env and fill in the values before starting any service.

Never commit .env to version control. Variables marked Secret contain credentials or private keys that must be kept out of source control and logs.

API Gateway

API_GATEWAY_HOST

string

required

Host address the API Gateway binds to. Default: 0.0.0.0.

API_GATEWAY_PORT

number

required

Port the API Gateway HTTP server listens on. Default: 5000.

API_GATEWAY_PROTOCOL

string

required

Protocol used for API Gateway URLs in Swagger server list. Example: http.

API_GATEWAY_PROTOCOL_SECURE

string

Secure protocol variant. Example: https.

API_ENDPOINT

string

Host and port used when building Swagger server URLs. Example: localhost:5000.

API_ENDPOINT_PORT

number

Port component for API_ENDPOINT. Example: 5000.

SOCKET_HOST

URL

WebSocket host URL. Example: http://localhost:5000.

ENABLE_CORS_IP_LIST

string

Comma-separated list of origins allowed by CORS. Leave empty to disable CORS restrictions. Example: https://app.example.com,https://dashboard.example.com.

HIDE_EXPERIMENTAL_OIDC_CONTROLLERS

boolean

When true, hides OID4VC, OID4VP, and x509 controller routes from the OpenAPI documentation. Default: true.

PUBLIC_LOCALHOST_URL

URL

Localhost API URL added as a Swagger server entry.

PUBLIC_DEV_API_URL

URL

Development environment API URL added as a Swagger server entry.

PUBLIC_QA_API_URL

URL

QA environment API URL added as a Swagger server entry.

PUBLIC_PRODUCTION_API_URL

URL

Production environment API URL added as a Swagger server entry.

PUBLIC_SANDBOX_API_URL

URL

Sandbox environment API URL added as a Swagger server entry.

APP_PROTOCOL

string

Application-level protocol identifier used in SSO redirect flows.

MODE

string

Runtime mode. Example: DEV.

Platform identity

PLATFORM_NAME

string

required

Display name of the platform. Used as the Swagger API title. Example: CREDEBL.

PLATFORM_LOGO

URL

URL of the platform logo image shown in emails and the web UI.

PLATFORM_WEB_URL

URL

Public URL of the platform web application.

PLATFORM_URL

URL

Base URL for the platform API. Example: https://devapi.credebl.id.

PUBLIC_PLATFORM_SUPPORT_EMAIL

string

Support email address displayed to users.

POWERED_BY

string

Organization name shown in “powered by” attribution.

POWERED_BY_URL

URL

URL linked to the “powered by” attribution.

UPLOAD_LOGO_HOST

URL

Domain used to construct public URLs for uploaded logo files.

FRONT_END_URL

URL

URL of the front-end application. Example: http://localhost:3000.

SHORTENED_URL_DOMAIN

URL

Domain of the S3 bucket that stores shortened URL objects. Example: https://bucket-name.s3.ap-east-1.amazonaws.com.

DEEPLINK_DOMAIN

URL

Domain used to generate deep-links. The platform appends url as a query parameter. Example: https://your-deeplink-domain?url=.

PLATFORM_ADMIN_EMAIL

string

required

Email address of the platform administrator account.

PLATFORM_PROFILE_MODE

string

Deployment environment label. Example: production.

OOB_BATCH_SIZE

number

Maximum number of out-of-band invitations dispatched in a single batch. Default: 10.

PROOF_REQ_CONN_LIMIT

number

Maximum concurrent proof-request connections. Default: 10.

Database

DATABASE_URL

string

required

Full Prisma-compatible PostgreSQL connection string. Example: postgresql://postgres:password@localhost:5432/postgres?schema=public.

POOL_DATABASE_URL

string

Pooled connection string (e.g., via Supabase PgBouncer). Used when connection pooling is required.

POSTGRES_HOST

string

required

PostgreSQL host. Example: 0.0.0.0.

POSTGRES_PORT

number

required

PostgreSQL port. Default: 5432.

POSTGRES_USER

string

required

PostgreSQL username. Default: postgres.

POSTGRES_PASSWORD

string

required

PostgreSQL password.

Treat this as a secret. Do not log or expose this value.

POSTGRES_DATABASE

string

required

Name of the PostgreSQL database.

DB_ALERT_ENABLE

boolean

When true, enables email alerts when the ledger_id column in org_agents is set to null. Requires the utility microservice.

DB_ALERT_EMAILS

string

Comma-separated list of email addresses that receive database alerts.

PRISMA_LOGS

string

Comma-separated Prisma log types. Example: error,warn. Adding query produces verbose logging for every SQL statement.

NATS messaging

NATS_URL

string

required

NATS server URL(s). Multiple servers can be provided as comma-separated values. Example: nats://0.0.0.0:4222.

NATS_HOST

string

required

NATS server hostname. Example: 0.0.0.0.

NATS_PORT

number

required

NATS server port. Default: 4222.

NATS_AUTH_TYPE

string

required

Authentication method for NATS connections. One of: nkey, creds, usernamePassword, none. Default: nkey.

NATS_USER

string

NATS username. Required when NATS_AUTH_TYPE=usernamePassword.

NATS_PASSWORD

string

NATS password. Required when NATS_AUTH_TYPE=usernamePassword.

Treat this as a secret.

NATS_CREDS_FILE

string

Absolute path to a NATS credentials file. Required when NATS_AUTH_TYPE=creds. Example: /platform/app_user.creds.

NOTIFICATION_NATS_AUTH_TYPE

string

Auth type override for the notification service NATS connection. Accepts the same values as NATS_AUTH_TYPE.

ENABLE_NATS_NOTIFICATION

boolean

Enables the NATS-based notification pathway. Default: false.

Per-service NKEY seeds

Each microservice authenticates to NATS using its own NKey seed. Required when NATS_AUTH_TYPE=nkey.

NKey seeds are private credentials. Treat every *_NKEY_SEED variable as a secret and rotate them if they are ever exposed.

API_GATEWAY_NKEY_SEED

string

NKey seed for the api-gateway service.

USER_NKEY_SEED

string

NKey seed for the user service.

ORGANIZATION_NKEY_SEED

string

NKey seed for the organization service.

AGENT_PROVISIONING_NKEY_SEED

string

NKey seed for the agent-provisioning service.

AGENT_SERVICE_NKEY_SEED

string

NKey seed for the agent-service service.

VERIFICATION_NKEY_SEED

string

NKey seed for the verification service.

ISSUANCE_NKEY_SEED

string

NKey seed for the issuance service.

CONNECTION_NKEY_SEED

string

NKey seed for the connection service.

ECOSYSTEM_NKEY_SEED

string

NKey seed for the ecosystem service.

CREDENTAILDEFINITION_NKEY_SEED

string

NKey seed for the credential-definition service.

SCHEMA_NKEY_SEED

string

NKey seed for the schema service.

UTILITIES_NKEY_SEED

string

NKey seed for the utilities service.

GEOLOCATION_NKEY_SEED

string

NKey seed for the geo-location service.

X509_NKEY_SEED

string

NKey seed for the x509 service.

OIDC4VC_ISSUANCE_NKEY_SEED

string

NKey seed for the oid4vc-issuance service.

OIDC4VC_VERIFICATION_NKEY_SEED

string

NKey seed for the oid4vc-verification service.

JetStream / streaming

AGGREGATE_STREAM

string

Name of the JetStream aggregate stream. Default: aggregate.

DID_STREAM

string

Name of the JetStream DID notification stream. Default: did-notify.

PULL_CONSUMER

string

Name of the JetStream pull consumer. Default: hub-pull-consumer.

CONSUMER_CONFIG_ACK_WAIT

number

Acknowledgement wait time in nanoseconds. Default: 10_000.

CONSUMER_CONFIG_MAX_DELIVER

number

Maximum delivery attempts before a message is considered dead. Default: 4.

Redis

REDIS_HOST

string

required

Redis server host. Example: 0.0.0.0.

REDIS_PORT

number

required

Redis server port. Default: 6379.

FILEUPLOAD_CACHE_TTL

number

Time-to-live in milliseconds for the file-upload cache stored in Redis.

SESSIONS_LIMIT

number

Maximum number of concurrent sessions a user can hold.

FIELD_UPLOAD_SIZE

number

Maximum file upload size in bytes. Default: 10485760 (10 MB).

Authentication

Supabase

SUPABASE_URL

URL

required

URL of your Supabase project. Example: https://xyzcompany.supabase.co.

SUPABASE_KEY

string

required

Supabase anonymous (public) API key.

Although this is the public anon key, treat it as a secret in server-side .env files.

SUPABASE_JWT_SECRET

string

required

JWT secret from your Supabase project settings. Used to verify tokens server-side.

This is a secret — never expose it in client-side code or logs.

Keycloak

KEYCLOAK_DOMAIN

URL

required

Base URL of the Keycloak server. Example: http://localhost:8080/.

KEYCLOAK_ADMIN_URL

URL

required

Keycloak admin console URL. Example: http://localhost:8080.

KEYCLOAK_MASTER_REALM

string

required

Name of the Keycloak master realm.

KEYCLOAK_MANAGEMENT_CLIENT_ID

string

required

Client ID of the management client in Keycloak.

KEYCLOAK_MANAGEMENT_CLIENT_SECRET

string

required

Secret of the management client.

Treat as a secret.

KEYCLOAK_REALM

string

required

Keycloak realm used by the platform. Example: credebl-platform.

PLATFORM_ADMIN_KEYCLOAK_ID

string

required

Client ID of the Keycloak client created for the platform admin console. Example: adminClient.

PLATFORM_ADMIN_KEYCLOAK_SECRET

string

required

Secret of the platform admin Keycloak client.

Treat as a secret.

PLATFORM_ADMIN_OLD_CLIENT_ID

string

Previous client ID — used when migrating users after a Keycloak client rename.

SSO clients

To support multiple SSO clients, add a set of four variables for each client and append its name to SUPPORTED_SSO_CLIENTS. The variable names follow the pattern {CLIENT-NAME}_CLIENT_ALIAS, {CLIENT-NAME}_DOMAIN, {CLIENT-NAME}_KEYCLOAK_MANAGEMENT_CLIENT_ID, and {CLIENT-NAME}_KEYCLOAK_MANAGEMENT_CLIENT_SECRET.

SUPPORTED_SSO_CLIENTS

string

Comma-separated list of enabled SSO client names. Example: CREDEBL,VERIFIER.

CREDEBL_CLIENT_ALIAS

string

Alias token that identifies the default CREDEBL SSO client. Example: CREDEBL.

CREDEBL_DOMAIN

URL

Redirect URL for the default CREDEBL client after login. Example: http://localhost:3000.

CREDEBL_KEYCLOAK_MANAGEMENT_CLIENT_ID

string

Encrypted Keycloak management client ID for the CREDEBL SSO client. Encrypt using CRYPTO_PRIVATE_KEY.

CREDEBL_KEYCLOAK_MANAGEMENT_CLIENT_SECRET

string

Encrypted Keycloak management client secret for the CREDEBL SSO client.

Store the encrypted value, not the plaintext secret.

Crypto

CRYPTO_PRIVATE_KEY

string

required

Private key used to encrypt/decrypt sensitive configuration values (e.g., Keycloak client secrets). Must match the key used in the Studio UI.

This is a master secret. Loss or exposure compromises all encrypted values.

FIDO / WebAuthn

FIDO_API_ENDPOINT

URL

Host and port of the FIDO (WebAuthn) server. Example: http://localhost:8000.

AWS / storage

All AWS keys are secrets. Use IAM roles or secret management tooling (e.g., AWS Secrets Manager) in production instead of plaintext environment variables.

General AWS credentials

AWS_PUBLIC_ACCESS_KEY

string

AWS access key ID for the public assets bucket.

AWS_PUBLIC_SECRET_KEY

string

AWS secret access key for the public assets bucket.

AWS_PUBLIC_REGION

string

AWS region for the public assets bucket. Example: ap-south-1.

AWS_PUBLIC_BUCKET_NAME

string

Name of the S3 bucket used for public assets.

AWS_ORG_LOGO_BUCKET_NAME

string

Name of the S3 bucket used for organization logos.

AWS_ACCESS_KEY

string

General AWS access key ID.

AWS_SECRET_KEY

string

General AWS secret access key.

AWS_REGION

string

General AWS region. Example: us-east-1.

AWS_BUCKET

string

General S3 bucket name.

AWS_ACCOUNT_ID

string

AWS account ID.

S3_BUCKET_ARN

string

ARN of the S3 bucket. Example: arn:aws:s3:::bucket-name.

S3 object store (dedicated credentials)

AWS_S3_STOREOBJECT_ACCESS_KEY

string

AWS access key ID for the object-store S3 bucket.

AWS_S3_STOREOBJECT_SECRET_KEY

string

AWS secret access key for the object-store S3 bucket.

AWS_S3_STOREOBJECT_REGION

string

AWS region for the object-store S3 bucket.

AWS_S3_STOREOBJECT_BUCKET

string

Name of the S3 bucket used for stored objects.

ECS (agent provisioning)

CLUSTER_NAME

string

ECS cluster name for Credo controller agents. Example: CREDO-CONTROLLER-CLUSTER.

TASKDEFINITION_FAMILY

string

ECS task definition family name. Example: CREDO-CONTROLLER-TASKDEFINITION.

ECS_SECURITY_GROUP_ID

string

Security group ID for ECS tasks.

ECS_SUBNET_ID

string

Subnet ID for ECS tasks.

FILESYSTEMID

string

EFS filesystem ID used by ECS tasks.

INBOUND_TG_ARN

string

ARN of the inbound target group for agent load balancing.

ADMIN_TG_ARN

string

ARN of the admin target group for agent load balancing.

Email

EMAIL_PROVIDER

string

required

Active email provider. One of: resend, sendgrid, ses, smtp.

RESEND_API_KEY

string

API key for the Resend email service. Required when EMAIL_PROVIDER=resend. Example: re_xxxxxxxxxx.

Treat as a secret.

SENDGRID_API_KEY

string

API key for SendGrid. Required when EMAIL_PROVIDER=sendgrid. Example: SG.xxxxxxx.

Treat as a secret.

AWS_SES_REGION

string

AWS region for SES. Required when EMAIL_PROVIDER=ses. Example: ap-south-1.

AWS_SES_ACCESS_KEY

string

AWS access key ID for SES.

AWS_SES_SECRET_KEY

string

AWS secret access key for SES.

Treat as a secret.

SMTP_HOST

string

SMTP server hostname. Required when EMAIL_PROVIDER=smtp. Example: smtp.gmail.com.

SMTP_PORT

number

SMTP server port. Example: 587.

SMTP_USER

string

SMTP username / sender address.

SMTP_PASS

string

SMTP password.

Treat as a secret.

Agent

AGENT_HOST

string

SSH-style address of the agent host VM. Example: [email protected].

AGENT_PROTOCOL

string

Protocol for agent communication. Example: http.

AGENT_API_KEY

string

required

API key for the base agent wallet. Must be at least 16 characters. Example: supersecret-that-too-16chars.

Treat as a secret.

AFJ_VERSION

string

Docker image tag for the AFJ (Aries Framework JavaScript) agent. Example: afj-0.4.1:latest.

AFJ_AGENT_SPIN_UP

string

Absolute path to the agent startup shell script. Example: /apps/agent-provisioning/AFJ/scripts/start_agent.sh.

AFJ_AGENT_ENDPOINT_PATH

string

Directory path for agent endpoint configuration files. Example: /apps/agent-provisioning/AFJ/endpoints/.

WALLET_STORAGE_HOST

string

Host (IP address) of the PostgreSQL database used for agent wallet storage.

WALLET_STORAGE_PORT

number

Port of the wallet storage database. Default: 5432.

WALLET_STORAGE_USER

string

Username for the wallet storage database. Default: postgres.

WALLET_STORAGE_PASSWORD

string

Password for the wallet storage database.

Treat as a secret.

PLATFORM_WALLET_NAME

string

Name of the platform administrator wallet. Default: platform-admin.

PLATFORM_WALLET_PASSWORD

string

Encrypted password for the platform wallet. Encrypt with crypto-js using CRYPTO_PRIVATE_KEY.

Treat as a secret.

PLATFORM_SEED

string

32-character seed used when creating the platform DID.

PLATFORM_ID

string

Unique identifier for this platform instance.

FILE_SERVER

string

URL of the file server used to host tails files and other agent assets.

FILE_SERVER_PORT

number

Port of the file server. Default: 8081.

FILE_SERVER_USER

string

Username for file server SSH access. Default: credebl.

FILE_SERVER_HOST

string

Hostname or IP of the file server. Example: 0.0.0.0.

SCHEMA_FILE_SERVER_URL

URL

URL of the schema file server (used for Polygon-based W3C schemas).

SCHEMA_FILE_SERVER_TOKEN

string

Authentication token for the schema file server.

Treat as a secret.

PROTOCOL

string

Protocol used by agent endpoint URLs. Example: http.

Observability

ELK Stack

ELK_LOG

boolean

Enables ELK-based structured logging. Example: true.

CONSOLE_LOG_FLAG

boolean

Enables console output of ELK-format logs. Example: true.

LOG_LEVEL

string

Log verbosity level. Example: debug.

ELK_LOG_PATH

URL

Elasticsearch endpoint for log ingestion. Example: http://localhost:9200/.

ELK_USERNAME

string

Elasticsearch username. Example: elastic.

ELK_PASSWORD

string

Elasticsearch password.

Treat as a secret.

ORGANIZATION

string

Organization label attached to log entries. Example: credebl.

CONTEXT

string

Context label attached to log entries. Example: platform.

APP

string

Application label attached to log entries. Example: api.

HOSTNAME

string

Hostname or unique identifier for this service instance. Example: localhost.

OpenTelemetry

IS_ENABLE_OTEL

boolean

Enables the OpenTelemetry SDK. Default: false.

OTEL_SERVICE_NAME

string

Logical service name shown in observability tools such as SigNoz. Example: CREDEBL-PLATFORM-SERVICE.

OTEL_SERVICE_VERSION

string

Service version reported to the OTel collector. Example: 1.0.0.

OTEL_TRACES_OTLP_ENDPOINT

URL

OTLP/HTTP endpoint for trace export. Example: http://localhost:4318/v1/traces.

OTEL_LOGS_OTLP_ENDPOINT

URL

OTLP/HTTP endpoint for log export. Example: http://localhost:4318/v1/logs.

OTEL_HEADERS_KEY

string

API key or token used to authenticate with the OTel collector.

Treat as a secret.

OTEL_LOGGER_NAME

string

Name of the OpenTelemetry logger. Example: credebl-platform-logger.

Get Started

Configuration

Deployment

Core Concepts

API Gateway

Platform identity

Database

NATS messaging

Per-service NKEY seeds

JetStream / streaming

Redis

Authentication

Supabase

Keycloak

SSO clients

Crypto

FIDO / WebAuthn

AWS / storage

General AWS credentials

S3 object store (dedicated credentials)

ECS (agent provisioning)

Email

Agent

Observability

ELK Stack

OpenTelemetry

Build docs developers (and LLMs) love

Get Started

Configuration

Deployment

Core Concepts

​API Gateway

​Platform identity

​Database

​NATS messaging

​Per-service NKEY seeds

​JetStream / streaming

​Redis

​Authentication

​Supabase

​Keycloak

​SSO clients

​Crypto

​FIDO / WebAuthn

​AWS / storage

​General AWS credentials

​S3 object store (dedicated credentials)

​ECS (agent provisioning)

​Email

​Agent

​Observability

​ELK Stack

​OpenTelemetry

Build docs developers (and LLMs) love

API Gateway

Platform identity

Database

NATS messaging

Per-service NKEY seeds

JetStream / streaming

Redis

Authentication

Supabase

Keycloak

SSO clients

Crypto

FIDO / WebAuthn

AWS / storage

General AWS credentials

S3 object store (dedicated credentials)

ECS (agent provisioning)

Email

Agent

Observability

ELK Stack

OpenTelemetry