REST API

The REST API reference provides detailed information about the REST API endpoints available in comby. Developers can use this reference to understand the available endpoints, request and response formats, and authentication requirements. The reference is organized by domain, with each domain containing a set of related endpoints for managing specific resources.

TIP

Under the Getting Started - REST API, you can find detailed instructions on how to add custom domains and corresponding endpoints to the existing comby default REST API.

➡️ REST API (auto-generated; OpenAPI 3.1)

(That is a copy of the latest auto-generated REST API documentation using comby defaults only.)

INFO

Note that the REST API and Reference Documentation are available at runtime in the final application. The REST API is fully generated automatically. The Reference Documentation can be generated at build time using a command and is embedded as static Markdown into the final application, allowing it to be accessed through a user interface. By default endpoints are:

• /docs/api for the REST API documentation
• /docs/ref for the Reference documentation

An example: If your web server is running on localhost:8090, you can access the documentation at the following URL: http://localhost:8090/docs/api and http://localhost:8090/docs/ref - if using comby defaults.

Throttling

Throttling is a technique used to control the amount of incoming requests to a server or API. It helps prevent abuse, ensures fair usage, and maintains the performance and stability of the system.

Comby implements request rate limiting using a cache-based throttling mechanism. It tracks requests per action and object combination within a sliding time window (default: 1 minute). When the maximum number of requests is exceeded, subsequent requests are rejected until the window expires.

Default Throttle Limits

The following default throttle limits are applied to specific account operations:

Scope	Default Limit	Window
Account Registration (Email/Password)	10 requests	per minute
Account Registration (Opaque)	10 requests	per minute
Account Login (Email/Password)	10 requests	per minute
Account Login (Opaque)	10 requests	per minute
Password Reset (Email/Password)	5 requests	per minute
Password Reset (Opaque)	10 requests	per minute
One-Time Token Validation	10 requests	per minute
Default (all other operations*)	60 requests	per minute

• only specific endpoints are throttled, e.g., /api/v2/account/register/emailpassword.

Environment Variables

You can customize throttle limits using environment variables:

Global Default

• COMBY_DEFAULT_THROTTLE_MAX_REQUESTS Sets the default maximum requests per minute for operations without specific limits. Default: 60 Example: COMBY_DEFAULT_THROTTLE_MAX_REQUESTS=100

Scope-Specific Limits

Override limits for specific operations using the pattern COMBY_DEFAULT_THROTTLE_<SCOPE>_MAX_REQUESTS:

• COMBY_DEFAULT_THROTTLE_ACCOUNT_REGISTER_EMAILPASSWORD_MAX_REQUESTS Account registration with email/password Default: 10

• COMBY_DEFAULT_THROTTLE_ACCOUNT_REGISTER_OPAQUE_MAX_REQUESTS Account registration with opaque authentication Default: 10

• COMBY_DEFAULT_THROTTLE_ACCOUNT_LOGIN_EMAILPASSWORD_MAX_REQUESTS Account login with email/password Default: 10

• COMBY_DEFAULT_THROTTLE_ACCOUNT_LOGIN_OPAQUE_MAX_REQUESTS Account login with opaque authentication Default: 10

• COMBY_DEFAULT_THROTTLE_ACCOUNT_PASSWORD_RESET_EMAILPASSWORD_MAX_REQUESTS Password reset requests with email/password Default: 5

• COMBY_DEFAULT_THROTTLE_ACCOUNT_PASSWORD_RESET_OPAQUE_MAX_REQUESTS Password reset requests with opaque authentication Default: 10

• COMBY_DEFAULT_THROTTLE_AUTH_ACCOUNT_ONE_TIME_TOKEN_VALIDATE_MAX_REQUESTS One-time token validation attempts Default: 10

TIP

All throttle limits are per minute and per unique object (e.g., per IP address, per user ID). The time window is currently fixed at 1 minute and cannot be configured via environment variables.