Skip to main content

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 and authorization​

The Core supports three authentication modes to fit different deployment scenarios and security requirements.

No authentication​

Disables authentication entirely. The service accepts all incoming requests without validating credentials, checking permissions, enforcing tenant separation, or logging users.

Security Warning

This mode removes all built-in access controls and user attribution in logging. Use only when:

  • You understand the associated risks
  • Authentication and authorization are enforced by infrastructure components
  • You have implemented compensating security controls
  • Or you are running in local development environments

Configure for no authentication​

app:
  auth:
    mode: INSECURE_NONE

Static token​

Uses a single shared bearer token for authentication. Clients must include this token in the Authorization header of each request.

  • Use when: You need simple authentication without complex IAM integration, such as service-to-service communication with a shared secret.
  • Limitations:
    • Tenant separation is not enforced
    • All clients share the same token, providing no user attribution or fine-grained access control
Security Warning

This mode provides very limited authentication. Most productive deployments should not use this configuration.

Configure for static token​

app:
  auth:
    mode: STATIC
    staticToken: "your-secure-token"

Or pass your token as an environment variable:

ONE_app__auth__staticToken="your-secure-token"
Hint

Generate a cryptographically secure token using openssl rand -hex 32 or another qualified tool.

Secure Token Service​

Integrates with your organization's IAM provider through our Secure Token Service (STS). Users authenticate with their IAM credentials and the STS exchanges the authorization token for an application-specific token. Enabling STS mode configures the Core service to validate STS-issued tokens on every incoming request, obtained through our Secure Token Service.

Configure the STS​

  • Set app.auth.stsTokenValidation.jwksUri to your JWKS endpoint
  • Configure app.auth.stsTokenValidation.aud and app.auth.stsTokenValidation.iss to match your STS token claims
  • Optionally adjust app.auth.stsTokenValidation.ttlJwks for JWKS cache duration

Example:

app:
  auth:
    mode: STS
    stsTokenValidation:
      aud: one-core
      iss: "https://desk.example.com"
      jwksUri: "https://desk.example.com/.well-known/jwks.json"
      ttlJwks: 600
info

For detailed information about authentication architecture, token structures, and integration patterns, see Authentication and authorization.

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 version 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"