Core service configuration

Learn the essential Core service configurations.

The Core service provides APIs for the complete lifecycle of credentials. Core configuration consists primarily in:

• Credential protocols and formats
• Where and how the Core is available to other services
• Security settings

Key parameters are highlighted below. For all available options, see the complete reference.

Authentication token

Most endpoints require authentication using a bearer token. Set your authentication token in the configuration:

app:
  authToken: "your-secure-token"

Or using an environment variable:

ONE_app__authToken="your-secure-token"

Generate a cryptographically secure token — such as with openssl rand -hex 32 — and update this from the default for production deployments.

API usage

Include the token in the Authorization header for protected endpoints:

Authorization: Bearer your-secure-token

Example request:

curl -L '/api/organisation/v1' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <your-secure-token>'

Application server

These settings control your core application service - where it listens for connections and how other services find it.

Base URL

Set coreBaseUrl to where your application is accessible from the outside. Other services use this for API calls, and the frontend uses it for routing:

• https://app.mycompany.com

• http://localhost:3000 for local development

Server Configuration

The serverIp and serverPort control the internal network settings - typically 0.0.0.0:3000 for both development and production.

Example configuration

Development:

app:
  serverIp: "0.0.0.0"
  serverPort: 3000
  coreBaseUrl: "http://localhost:3000"

Production:

app:
  serverIp: "0.0.0.0"
  serverPort: 3000
  coreBaseUrl: "https://app.mycompany.com"

Be sure to configure the corresponding security settings to match whether you're using HTTP (development) or HTTPS (production).

Required encryption keys

Encryption keys are required in several places in the Core configuration:

1. Any instance of keyStorage.type="INTERNAL"

2. Any instance of issuanceProtocol that is a draft of OpenID4VCI

Keys must be a 32 byte hex-encoded value. Use openssl rand -hex 32 or another qualified tool to generate a cryptographically-secure key.

Example using environment variables:

ONE_keyStorage__INTERNAL__params__private__encryption="533c29f3942d824bc163dc91079d209566dff1b30679188d0f2317e6fa2c3bac"
ONE_issuanceProtocol__OPENID4VCI_DRAFT13__params__private__encryption="5874564335f8b0865df744d86c8e2a7c90f223474c52a692953e1182a2b3457a"
ONE_issuanceProtocol__OPENID4VCI_DRAFT13_SWIYU__params__private__encryption="aec38cbd853fe1ffaadbc7f6b25cb1701910ee4af39cfade18c4bd19e1c9fd13"

Security settings

Configure authentication, transport security, and endpoint access controls to protect your application in different environments.

Control HTTP vs. HTTPS transport

Set allowInsecureHttpTransport to true only for development environments or controlled internal networks. Keep this false in production to enforce TLS/SSL encryption for all communication.

Restrict endpoint access by zone

Use these settings to control which API endpoints are available in different network zones. The Core has two kinds of endpoints:

• /api are "management" endpoints. These endpoints control internal resources such as organizations, cryptographic keys, credentials and proofs. Set enableManagementEndpoints to true for internal zone deployments; false for public zones.

• /ssi are "external" endpoints. These endpoints include lower-level, protocol specific endpoints for credential exchange and public-facing resource retrieval. Set enableExternalEndpoints to true for public- facing deployments.

Enable VC-API benchmarking (optional)

Turn on insecureVcApiEndpointsEnabled only if you need /vc-api endpoints for benchmarking with canivc.com. Keep disabled otherwise.

Example configuration

Development:

app:
  authToken: "dev-token-change-me"
  allowInsecureHttpTransport: true
  enableExternalEndpoints: true
  enableManagementEndpoints: true
  insecureVcApiEndpointsEnabled: false

Production (public zone):

app:
  authToken: "your-secure-production-token"
  allowInsecureHttpTransport: false
  enableExternalEndpoints: true
  enableManagementEndpoints: false
  insecureVcApiEndpointsEnabled: false

Production (internal zone):

app:
  authToken: "your-secure-production-token"
  allowInsecureHttpTransport: false
  enableExternalEndpoints: false
  enableManagementEndpoints: true
  insecureVcApiEndpointsEnabled: false

Database configuration

Configure a database using a MySQL connection string:

app:
  databaseUrl: "mysql://core:{{DB-PASSWORD}}@localhost/core"

Debugging and error handling

Configure how your application handles errors and provides debugging information to help you troubleshoot issues effectively.

Hide error details in production

Set hideErrorResponseCause to true in production to prevent exposing internal implementation details to clients. Keep it false in development so you can see full error information for debugging.

Enable JSON tracing for API debugging

Turn on traceJson to get detailed request and response information in JSON format. This helps when debugging API call flows, but generates verbose output.

Control logging verbosity by component

Use traceLevel to set different log levels for specific parts of your applicatioin. Specify namespace=level pairs separated by commas:

traceLevel: "database=debug,auth=info,api=warn"

Set up error monitoring with Sentry

Configure sentryDsn with your Sentry project's Data Source Name to automatically track errors. Set sentryEnvironment to label errors by deployment environment — for example "production" or "staging".

Example configuration

Development:

app:
  hideErrorResponseCause: false
  traceJson: true
  traceLevel: "database=debug,api=debug"
  sentryEnvironment: "development"

Production:

app:
  hideErrorResponseCause: true
  traceJson: false
  traceLevel: "database=warn,api=error"
  sentryDsn: "https://your-sentry-dsn@sentry.io/project"
  sentryEnvironment: "production"