API Catalogs, Spaces & Roles

API Builder has its own two-level hierarchy — API Catalog → API Space — that scopes who can see, develop, and publish which API definitions. It exists purely to govern API definitions; it carries no LLM provider configuration or execution environment of its own.

Not the same "Catalogs & Spaces" you may have seen elsewhere

Hrida.ai also has a separate, general-purpose Catalogs & Spaces feature used for partitioning an instance into isolated business units with their own LLM providers — that system is used across many parts of the product, including Agent Builder workflow nodes. API Builder's API Catalogs and API Spaces are a completely different, unrelated set of tables, scoped only to API definitions. The two features share a name and a two-level shape by convention, nothing else — an API Space membership grants no access in the other system, and vice versa.

Structure

API Catalog  (e.g., "Partner Integrations")
 └─ API Space: "Payments Team"   — members with roles
 └─ API Space: "Logistics Team"  — members with roles

API definitions belong to exactly one API Space (or none — see "Platform-wide definitions" below).

An API Catalog is a named grouping (with a unique slug) that can be active or suspended. An API Space lives inside exactly one catalog and is the actual unit of membership — each space has its own members, each with a role.

Roles

Roles are checked at the API Space level and apply to the API definitions inside that space:

Role	What it can do
`viewer`	Read-only access to published API definitions in the space, and use of them in agents
`api_developer`	Create and edit definitions (while draft/rejected), add mappers to drafts, submit for review
`lifecycle_manager`	Everything `api_developer` can, plus approve/reject/publish, change mappers on published APIs and rotate secrets
`space_admin`	Everything above, plus manage space membership and pull a published API back to draft

Every space member, whatever their role, can call the space's published APIs from their own agents — see Who can use a published API. Adding or removing a member updates that access immediately.

A user's effective role on a specific API definition is resolved in this order: a global Hrida.ai instance admin always resolves to admin (the highest level, see Lifecycle for what that unlocks); otherwise, if the definition belongs to a space, their membership role in that space applies; otherwise, the definition's own creator gets api_developer on it; everyone else gets viewer.

catalog_admin is reserved, not enforced today

The role vocabulary also defines a catalog_admin role, but nothing in the current implementation actually checks for it — creating, updating, or deleting an API Catalog or an API Space itself requires a full instance admin, not just a catalog-level role. Only membership roles inside a space (the table above) are enforced day-to-day.

Same access control model as Agent Builder

API Builder's role tiers and lifecycle-gating rules are deliberately modeled on Agent Builder's own role-based access control — same shape, same tier boundaries, just a different resource type and role name for "developer":

Access level	Agent Builder role	API Builder role	Can do
Read-only	(Read access)	`viewer`	View, no create/edit
Build	`agent_developer`	`api_developer`	Create/edit while in Draft or Rejected; submit for review
Review	`lifecycle_manager`	`lifecycle_manager`	Everything above, plus Approve / Reject
Space owner	`space_admin`	`space_admin`	Everything above, plus manage membership and pull a published item back to Draft
Instance owner	`admin`	`admin`	Everything above, plus two shortcuts: publish directly from Draft (skipping review), and pull a staged item straight back to Draft

This is a structural parallel, not a shared implementation — see the callout above and Lifecycle, Versions & Audit Log for API Builder's own transition table, which mirrors Agent Builder's Role reference rule for rule.

Who can use API Builder at all

Two switches sit above these roles, and both are enforced by the server:

ENABLE_API_BUILDER turns API Builder on or off for the whole instance.
The features.api_builder user permission (Admin Settings → Users → permissions) controls which non-admin users can use it.

A user without API Builder access gets 403 from every API Builder endpoint, regardless of their space roles. The API Gateway is not affected — published APIs keep working for agents.

Platform-wide definitions

An API definition's api_space_id can be left empty, in which case it isn't scoped to any space at all — only an instance admin can create, see, or manage it. Use this for APIs that shouldn't be delegated to any particular team.

Managing catalogs, spaces, and members

All under /api/v1/api-catalogs:

Method	Path	Notes
`GET` / `POST`	`/`	List catalogs (admins see all; others see only catalogs where they have a space membership) / create a catalog (admin only)
`GET` / `PATCH` / `DELETE`	`/{catalog_id}`	Admin only for update/delete
`GET` / `POST`	`/{catalog_id}/spaces`	List spaces in a catalog / create a space (admin only)
`GET` / `PATCH` / `DELETE`	`/{catalog_id}/spaces/{space_id}`	Update requires space-admin role; delete requires instance admin
`GET` / `POST`	`/{catalog_id}/spaces/{space_id}/members`	List members / add a member (requires space-admin role)
`PATCH` / `DELETE`	`/{catalog_id}/spaces/{space_id}/members/{user_id}`	Change a member's role or remove them (requires space-admin role)

Lifecycle, Versions & Audit Log — the transition table these roles gate
Catalogs & Spaces — the unrelated, general-purpose multi-tenancy feature this is often confused with by name

Structure​

Roles​

Same access control model as Agent Builder​

Who can use API Builder at all​

Platform-wide definitions​

Managing catalogs, spaces, and members​

Related​