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

For CORS configuration options see the CORS Configuration Reference.

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:

The first path segment is extracted from the request URL
The Gateway looks up this segment in the paths configuration
If a matching path is found, the request is forwarded to the configured service instance
The request is forwarded with additional headers for service-to-service authentication
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.