Interfaces & Services

The interfaces property in blocklet.yml is the primary mechanism for a blocklet to expose itself to the world. It defines all the entry points, such as web UIs, APIs, or other accessible endpoints. Each interface can be configured with specific routing, port mapping, and built-in services like authentication to secure its resources.

This section details the configuration of the interfaces array and its associated properties, including how to attach and configure services.

The interfaces Array#

A blocklet can define multiple interfaces in this array. Each object in the array represents a distinct entry point.

Interface Properties#

Each interface object is defined by the following properties, derived from the interfaceSchema:

Property	Type	Description
type	String	Required. The type of interface. Valid values are web and well-known. web is for standard web applications and APIs.
name	String	Required. A unique, human-readable name for the interface (e.g., public_url, admin_api).
path	String	The internal path within the blocklet that this interface serves. Defaults to /.
prefix	String	The URL prefix where this interface is mounted. A value of * (the default) allows it to be mounted at any path chosen by the user. A well-known interface prefix must start with /.well-known.
port	String or Object	Specifies port mapping. Can be a string referencing an environment variable (e.g., 'BLOCKLET_PORT', the default) or an object for explicit mapping: { internal: 'INTERNAL_PORT_VAR', external: 3000 }.
protocol	String	The protocol used by the interface. Valid values are http, https. Defaults to http.
containerPort	Number	The port inside the container to expose when using Docker.
hostIP	String	Binds the interface to a specific host IP address (IPv4 or IPv6).
proxyBehavior	String	Defines how requests are handled. service (default) routes requests through ABT Node's internal services (like auth), while direct bypasses them for a direct connection.
cacheable	Array	An array of path prefixes (e.g., /assets) within the blocklet that are safe to be cached by the hosting environment.
services	Array	An array of built-in services to apply to this interface. See the Configuring Services section below.
endpoints	Array	An array defining specific API endpoints exposed by this interface, complete with metadata. See Endpoint Properties.
pageGroups	Array	An array of strings used to group pages, which can be utilized by the user interface for organizational purposes (e.g., creating menu sections).

Endpoint Properties#

The endpoints array provides metadata for specific API endpoints, which can be used by other blocklets or tools for service discovery. This is defined by the endpointSchema.

Property	Type	Description
type	String	Required. A string identifying the endpoint's purpose (e.g., health-check, user-profile).
path	String	Required. The path for this specific endpoint, relative to the interface's path.
meta	Object	An object containing additional metadata, such as vcType for Verifiable Credentials, payable to indicate if it requires payment, and params to describe expected request parameters.

Example: Basic Web and API Interfaces#

Configuring Services#

The services array within an interface allows you to enable and configure built-in functionalities provided by the ABT Node environment. Each service object requires a name and a config object.

The most commonly used service is auth for access control.

The auth Service#

The auth service protects an interface by enforcing authentication and authorization rules. Its configuration is defined by the authConfigSchema.

Config Property	Type	Description
whoCanAccess	String	Defines who can access the interface. Valid options: owner (restricts to the node owner), invited (owner and invited users), all (any authenticated user).
blockUnauthenticated	Boolean	If true, users who are not logged in will be redirected to the login page.
blockUnauthorized	Boolean	If true, authenticated users who do not meet the whoCanAccess criteria will be shown an unauthorized page.
allowSwitchProfile	Boolean	If true, allows users with multiple profiles to switch between them within the blocklet's context.
ignoreUrls	Array	An array of URL paths or patterns that will bypass the authentication check.
profileFields	Array	Deprecated. Previously used to request specific user profile fields.

Example: Interface with Authentication#

This example configures a web interface that is only accessible to the node owner and any users they have invited. The login page itself (/login) is excluded from the authentication check.

By correctly defining interfaces and services, you can control exactly how your blocklet is exposed and secured. You are now ready to learn how to build more complex applications by composing multiple blocklets together.

Next: Composition (Components).