Gateway Service Reference

The gateway service acts as an intelligent HTTP router and proxy for Vidos services, providing a unified entry point for client applications while handling service discovery, authentication, and request forwarding. Rather than processing credentials or performing verification directly, the gateway coordinates access to specialized Vidos services through configurable path-based routing.

The gateway handles cross-origin resource sharing (CORS) for web applications, manages service-to-service authentication, and provides seamless request forwarding to configured service instances. By centralizing routing and access control, it enables secure and efficient communication between client applications and the distributed Vidos service architecture.

Request Routing

The gateway implements path-based request routing that maps URL paths to specific Vidos service instances:

Component	Description	Processing Type
Path Resolution	Extracts the first path segment for route lookup	Direct processing
Service Discovery	Maps paths to configured service instances	Configuration lookup
Request Forwarding	Proxies requests to target services	HTTP forwarding
Response Streaming	Streams responses back to clients	Direct passthrough

The gateway processes incoming requests by extracting the first path segment, looking up the corresponding service configuration, and forwarding the remaining path to the target service instance. This architecture enables flexible service composition while maintaining clean URL structures.

Supported Service Types

The gateway can route requests to any of the core Vidos services based on configuration:

Service Type	Description	Use Case	Authentication Support
Authorizer	OpenID4VP authorization workflows	Credential presentation flows	Account + Managed roles
Resolver	DID document resolution	Identity verification	Account + Managed roles
Verifier	Cryptographic verification	Signature and proof validation	Account + Managed roles
Validator	Structural credential validation	Schema and format validation	Account + Managed roles

Each service type can be configured with multiple instances, allowing for specialized routing based on different use cases, security requirements, or performance characteristics.

The gateway provides comprehensive CORS support for web applications accessing Vidos services:

CORS Feature	Description	Configuration Options	Security Considerations
Origin Control	Restricts requests by origin domain	Whitelist, wildcards	Prevents unauthorized domains
Method Filtering	Controls allowed HTTP methods	GET, POST, PUT, PATCH, DELETE	Limits attack surface
Header Management	Configures allowed/exposed headers	Custom headers, credentials	Controls data exposure
Credential Handling	Manages cookie and auth credentials	Enable/disable flags	Authentication integration

CORS configuration applies to all routed services, providing consistent cross-origin behavior across the entire Vidos service ecosystem while maintaining security boundaries.

Service Authentication

The gateway handles service-to-service authentication automatically when forwarding requests:

Authentication Headers

The gateway adds authentication and context headers to all forwarded requests:

Service Role Authentication: Uses configured service roles for authorization
Account Context: Includes account ID for multi-tenant isolation
Regional Context: Provides regional information for compliance
Resource Context: Specifies target service and instance details
Origin Tracking: Maintains original request context for auditing

Service Role Types

The gateway supports both account-owned and managed service roles:

Account Roles: Custom roles defined by the account owner
Managed Roles: Predefined roles managed by Vidos platform

For details on service role configuration and management, see the Service Roles Reference.

API Reference

The gateway service exposes management APIs for instance and configuration management:

Instance Management

Create Instance: Deploy new gateway instances with custom configurations
Update Instance: Modify existing gateway routing and CORS settings
Delete Instance: Remove gateway instances and clean up resources
Get Instance: Retrieve detailed instance information and status
List Instances: View all gateway instances for an account

Configuration Management

Create Configuration: Define reusable gateway configurations
Update Configuration: Modify routing paths and service mappings
Delete Configuration: Remove configuration templates
Get Configuration: Retrieve specific configuration details
List Configurations: View all available configurations

Request Processing Flow

When the gateway receives a request, it follows this processing sequence:

Status Verification: Confirms the gateway instance is running
CORS Handling: Processes preflight requests and applies CORS headers
Path Extraction: Extracts the first path segment for routing lookup
Service Resolution: Maps the path to a configured service instance
Authentication Setup: Adds service-to-service authentication headers
Request Forwarding: Proxies the request to the target service
Response Streaming: Streams the service response back to the client

This flow ensures secure, efficient request routing while maintaining full HTTP compatibility and preserving request/response semantics.

Configuration

The gateway service configuration controls routing behavior, CORS policies, and service integration. Key configuration areas include:

CORS Configuration: Controls cross-origin access policies for web applications
Path Configuration: Maps URL paths to specific service instances and authentication
Service Instance References: Specifies target services and authentication roles

For comprehensive information about configuring the gateway service, including all available options, routing examples, CORS settings, and service integration patterns, see the Configuration Reference.

Service Integration

The gateway integrates with all Vidos services through configurable routing paths:

Authorizer Integration

Route credential presentation and authorization requests to authorizer instances for OpenID4VP processing. The gateway forwards authentication flows while maintaining session context and security boundaries.

For details on authorizer capabilities, see the Authorizer Service Documentation.

Resolver Integration

Route DID resolution requests to resolver instances for identity document retrieval. The gateway enables efficient DID resolution while providing caching and load balancing capabilities.

For details on resolution processes, see the Resolver Service Documentation.

Verifier Integration

Route verification requests to verifier instances for cryptographic validation. The gateway coordinates signature verification and trust validation workflows.

For details on verification processes, see the Verifier Service Documentation.

Validator Integration

Route validation requests to validator instances for structural and content validation. The gateway enables schema validation and compliance checking workflows.

For details on validation processes, see the Validator Service Documentation.

Security Considerations

The gateway implements several security measures for safe request routing:

Request Sanitization

The gateway removes potentially dangerous headers from forwarded requests:

Host Headers: Prevents host header injection attacks
Forwarded Headers: Removes potentially spoofed forwarding information
Proxy Headers: Strips proxy-specific headers that could leak information

Service Isolation

Each routed service operates with isolated authentication and context:

Service Role Authentication: Each service receives appropriate authentication tokens
Account Isolation: Multi-tenant boundaries are maintained across all services
Resource Scoping: Services only access their designated resources

CORS Security

CORS configuration provides defense against cross-origin attacks:

Origin Validation: Restricts requests to authorized domains
Credential Protection: Controls when credentials are included in requests
Header Filtering: Limits exposed response headers to prevent information leakage

Performance Characteristics

The gateway is designed for high-performance request routing with minimal latency:

Request Processing

Streaming Responses: Responses are streamed directly to clients without buffering
Connection Reuse: HTTP connections to backend services are reused efficiently
Minimal Overhead: Routing decisions use fast path lookups with minimal processing

Scalability

Stateless Design: Gateway instances are stateless and can be scaled horizontally
Service Discovery: Dynamic service instance resolution supports scaling backend services
Load Distribution: Multiple gateway instances can handle traffic distribution

Additional Resources

Gateway Configuration Reference - Complete configuration options and routing examples
Service Instances Reference - Service instance configuration patterns
Service Roles Reference - Authentication and authorization configuration
CORS Configuration Reference - Cross-origin resource sharing settings
Authorizer Service Documentation - For authorization and presentation workflows
Resolver Service Documentation - For DID resolution capabilities
Verifier Service Documentation - For verification processes
Validator Service Documentation - For validation processes
Understanding Vidos Services - Service architecture and composition patterns