Gateway Configuration Reference

This reference documents the configuration options for the gateway service. The gateway routes incoming requests to configured Vidos services and handles cross-origin resource sharing (CORS) for web applications.

Core Configuration

This section documents the complete configuration provided by Vidos.

{
    "cors": {
        "enabled": false,
        "origin": ["*"],
        "credentials": false,
        "allowMethods": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
        "exposeHeaders": [],
        "allowHeaders": [],
        "maxAge": 86400
    },
    "paths": {}
}

Configuration Schema

The complete JSON Schema for the gateway configuration is available:

• Download gateway.schema.json

Configuration Options

cors Configuration

The cors object controls cross-origin resource sharing (CORS) behavior for the gateway service. CORS configuration determines which origins, methods, and headers are allowed when browser-based applications access the gateway.

Important: The cors configuration in the gateway controls external request access. All Vidos services (including the gateway) also support dashboard access through application-level CORS, which is configured separately via environment variables and is always enabled for management console access.

Configuration Schema

{
    "cors": {
        "enabled": "boolean",
        "allowHeaders": "string[]",
        "allowMethods": "string[]",
        "credentials": "boolean",
        "exposeHeaders": "string[]",
        "maxAge": "number",
        "origin": "string[]"
    }
}

enabled

• Type: boolean
• Default: false
• Description: Controls whether CORS is enabled for external requests to the gateway
• Note: Dashboard requests always receive CORS headers regardless of this setting

origin

• Type: string[]
• Default: ["*"]
• Description: List of allowed origins for external requests
• Format: Array of domain strings or "*" for all origins
• See: MDN: Access-Control-Allow-Origin

Example with wildcard:

{
    "cors": {
        "origin": ["*"]
    }
}

Example with specific origins:

{
    "cors": {
        "origin": ["https://app.example.com", "https://admin.example.com"]
    }
}

Effect on response headers (varies based on request origin):

Access-Control-Allow-Origin: https://app.example.com
Vary: Origin

credentials

• Type: boolean
• Default: false
• Description: Controls whether credentials (cookies, authorization headers) are allowed
• See: MDN: Access-Control-Allow-Credentials

Note: When credentials is true, the Access-Control-Allow-Origin header must be a specific origin (not *), so origin must be set accordingly.

{
    "cors": {
        "credentials": true,
        "origin": ["https://app.example.com"]
    }
}

Effect on response headers:

Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: https://app.example.com

allowMethods

• Type: string[]
• Default: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
• Description: HTTP methods allowed in CORS requests
• Allowed values: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD
• See: MDN: Access-Control-Allow-Methods

{
    "cors": {
        "allowMethods": ["GET", "POST", "OPTIONS"]
    }
}

Effect on response headers:

Access-Control-Allow-Methods: GET, POST, OPTIONS

allowHeaders

• Type: string[]
• Default: []
• Description: List of non-standard HTTP headers that browsers are allowed to send
• Behavior:
  • Applies to preflight requests and actual requests
  • Supplements CORS-safelisted request headers
  • Case-insensitive header matching
• CORS-safelisted headers (always allowed):
  • Accept
  • Accept-Language
  • Content-Language
  • Content-Type (with restrictions)
• See: MDN: Access-Control-Allow-Headers

{
    "cors": {
        "allowHeaders": ["Authorization", "X-Requested-With", "X-Custom-Header"]
    }
}

Effect on response headers:

Access-Control-Allow-Headers: Authorization, X-Requested-With, X-Custom-Header

exposeHeaders

• Type: string[]
• Default: []
• Description: Response headers that browsers are allowed to access
• Behavior:
  • Controls which response headers are visible to browser JavaScript
  • Supplements CORS-safelisted response headers
  • Case-insensitive header matching
• CORS-safelisted response headers (always exposed):
  • Cache-Control
  • Content-Language
  • Content-Length
  • Content-Type
  • Expires
  • Last-Modified
  • Pragma
• See: MDN: Access-Control-Expose-Headers

{
    "cors": {
        "exposeHeaders": ["X-Request-ID", "X-RateLimit-Limit", "X-RateLimit-Remaining"]
    }
}

Effect on response headers:

Access-Control-Expose-Headers: X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining

maxAge

• Type: number
• Default: 86400
• Description: Duration in seconds browsers should cache CORS preflight responses
• Unit: Seconds
• Valid range: 0 to 86400 (24 hours)
• See: MDN: Access-Control-Max-Age

{
    "cors": {
        "maxAge": 3600
    }
}

Effect on response headers:

Access-Control-Max-Age: 3600

CORS Architecture

The gateway uses a dual CORS architecture:

1. Instance-level CORS (configured here): Controls external/service-to-service requests through the cors configuration object. This is what you configure per gateway instance.

2. Application-level CORS (environment-based): All Vidos services, including the gateway, automatically support dashboard access through environment variables (EXPRESS_CORS_ORIGIN). This ensures the Vidos management console can always access services.

When a request arrives at the gateway:

• Requests from dashboard origins (configured in EXPRESS_CORS_ORIGIN) receive CORS headers for management console access
• Requests from other origins are subject to the instance-level cors configuration
• If instance-level CORS is disabled (enabled: false), only dashboard requests receive CORS headers

For more details on CORS options, see the CORS guide.

paths Configuration

The paths object defines mappings from URL paths to destination services. Each key in the object represents a path segment that will be routed to a specific service instance.

• Type: object (record of path keys to destination objects)
• Default: {}
• Description: Maps incoming request paths to service destinations
• Constraints:
  • Path keys must only contain alphanumeric characters, hyphens, and underscores ([-_a-zA-Z0-9])
  • Each path maps to a gateway destination object
• Effects:
  • Controls routing of incoming requests
  • Determines service integration points
  • Configures service-to-service authentication

Gateway Destination

Each value in the paths object is a gateway destination object:

• Type: object
• Properties:
  • type: "instance" (reference to a specific instance)
  • service: string (one of "authorizer", "resolver", "verifier", or "validator")
  • resourceId: string (resource ID of the target service instance)
  • serviceRole: Service role reference object
• Description: Specifies which service instance handles requests for a path

Example configuration with paths:

{
    "paths": {
        "auth": {
            "type": "instance",
            "service": "authorizer",
            "resourceId": "my-authorizer",
            "serviceRole": {
                "owner": "account",
                "resourceId": "auth-role"
            }
        },
        "resolve": {
            "type": "instance",
            "service": "resolver",
            "resourceId": "my-resolver",
            "serviceRole": {
                "owner": "managed",
                "resourceId": "resolver_all_actions"
            }
        }
    }
}

service

• Type: string (enum)
• Required: true
• Allowed values:
  • "authorizer": Routes requests to an authorizer service
  • "resolver": Routes requests to a resolver service
  • "verifier": Routes requests to a verifier service
  • "validator": Routes requests to a validator service
• Description: Specifies which type of service the request will be forwarded to

resourceId

• Type: string
• Required: true
• Description: The resource ID of the target service instance
• Constraints: Must reference an existing service instance of the specified service type
• Effects: Determines which specific instance handles requests for this path

serviceRole

Controls the authentication used when forwarding requests to the service.

• Type: object
• Required: true
• Properties:
  • owner: string (one of "account" or "managed")
  • resourceId: string (resource ID of the service role)
• Description: Service role reference for authentication
• See: Service Roles Reference

Example account-owned role:

{
    "serviceRole": {
        "owner": "account",
        "resourceId": "my-custom-role"
    }
}

Example managed role:

{
    "serviceRole": {
        "owner": "managed",
        "resourceId": "service_role_id"
    }
}

Request Forwarding

When a request is received at the Gateway, it’s processed as follows:

1. The first path segment is extracted from the request URL
2. The Gateway looks up this segment in the paths configuration
3. If a matching path is found, the request is forwarded to the configured service instance
4. The request is forwarded with additional headers for service-to-service authentication
5. The remaining path segments are preserved in the forwarded request

For example, with the following configuration:

{
    "paths": {
        "auth": {
            "type": "instance",
            "service": "authorizer",
            "resourceId": "main-authorizer",
            "serviceRole": {
                "owner": "account",
                "resourceId": "auth-role"
            }
        }
    }
}

A request to /auth/token would be forwarded to the authorizer instance with path /token. The gateway will add authentication headers for service-to-service communication.

Configuration Scenarios

Basic Gateway with Authorizer and Resolver

This example configures a gateway with paths for both an authorizer and a resolver service:

{
    "cors": {
        "enabled": true,
        "origin": ["https://example.com"],
        "credentials": true,
        "allowMethods": ["GET", "POST", "OPTIONS"],
        "allowHeaders": ["Content-Type", "Authorization"],
        "exposeHeaders": [],
        "maxAge": 86400
    },
    "paths": {
        "auth": {
            "type": "instance",
            "service": "authorizer",
            "resourceId": "main-authorizer",
            "serviceRole": {
                "owner": "managed",
                "resourceId": "authorizer_all_actions"
            }
        },
        "resolve": {
            "type": "instance",
            "service": "resolver",
            "resourceId": "main-resolver",
            "serviceRole": {
                "owner": "account",
                "resourceId": "resolver-service-role"
            }
        }
    }
}

Verification API Gateway

This example configures a gateway with paths for both verifier and validator services:

{
    "cors": {
        "enabled": true,
        "origin": ["*"],
        "credentials": false,
        "allowMethods": ["GET", "POST"],
        "allowHeaders": ["Content-Type"],
        "exposeHeaders": [],
        "maxAge": 3600
    },
    "paths": {
        "verify": {
            "type": "instance",
            "service": "verifier",
            "resourceId": "main-verifier",
            "serviceRole": {
                "owner": "account",
                "resourceId": "verifier-role"
            }
        },
        "validate": {
            "type": "instance",
            "service": "validator",
            "resourceId": "main-validator",
            "serviceRole": {
                "owner": "account",
                "resourceId": "validator-role"
            }
        }
    }
}

Multiple Service Endpoints

This example routes different authentication methods to separate service instances:

{
    "paths": {
        "login": {
            "type": "instance",
            "service": "authorizer",
            "resourceId": "login-authorizer",
            "serviceRole": {
                "owner": "account",
                "resourceId": "auth-admin-role"
            }
        },
        "mdl": {
            "type": "instance",
            "service": "authorizer",
            "resourceId": "mdl-authorizer",
            "serviceRole": {
                "owner": "account",
                "resourceId": "auth-admin-role"
            }
        },
        "resolve": {
            "type": "instance",
            "service": "resolver",
            "resourceId": "did-resolver",
            "serviceRole": {
                "owner": "managed",
                "resourceId": "resolver_all_actions"
            }
        }
    }
}

Service Instance References

The gateway uses service instance references to specify which service instances should handle requests for each path. For complete configuration options and examples, see the Service Instances Reference and Service Roles Reference.

Additional Resources

• Understanding Configuration in Vidos
• Service Instances Reference
• Service Roles Reference
• Authorizer Configuration Reference
• Resolver Configuration Reference
• Validator Configuration Reference
• Verifier Configuration Reference
• Understanding Vidos Services