Environment Variables

Complete reference for all environment variables used to configure the CREDEBL platform.

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.

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.

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.

SUPABASE_JWT_SECRET · string · required

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

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.

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.

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.

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.

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.

SENDGRID_API_KEY · string

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

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.

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.

---

Agent

AGENT_HOST · string

SSH-style address of the agent host VM. Example: username@0.0.0.0.

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.

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.

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.

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.

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.

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.

OTEL_LOGGER_NAME · string

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