umbraco-openapi-client

Configure a generated OpenAPI TypeScript client with Umbraco bearer-token authentication.

1|Updated May 21, 2026
One-click install
npx skills add https://github.com/1k-off/umbraco-observability-playground --skill umbraco-openapi-client-1k-off
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: umbraco-openapi-client
Source: https://github.com/1k-off/umbraco-observability-playground/tree/main/.agents/skills/umbraco-openapi-client
Command: npx skills add https://github.com/1k-off/umbraco-observability-playground --skill umbraco-openapi-client-1k-off

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents 401 Unauthorized failures and unsafe, unmaintainable calls by ensuring Umbraco backoffice API communication always uses the generated OpenAPI client with proper bearer-token auth.

Core Features & Use Cases

  • Authenticated OpenAPI client configuration: Sets the generated client’s base URL and credentials using Umbraco’s auth context so requests include the required bearer token.
  • Swagger-enabled TypeScript generation: Generates a typed TypeScript client from a documented swagger.json, enabling reliable integration with custom [BackOfficeRoute] controllers.
  • Backoffice UI consumption pattern: Supports typical scenarios like trees, workspaces, and custom backoffice screens that need to load or mutate data from extension endpoints.

Quick Start

Set up Swagger for your custom backoffice API route, generate the TypeScript client with @hey-api/openapi-ts, and configure the generated client in your extension entry point using host.consumeContext(UMB_AUTH_CONTEXT, ...).

Frequently Asked Questions about umbraco-openapi-client

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix 401 Unauthorized errors when calling custom backoffice API routes in Umbraco extensions?

Fix 401 Unauthorized errors in Umbraco extensions by configuring the OpenAPI TypeScript client with the UMB_AUTH_CONTEXT to automatically include bearer token credentials in fetch calls. This ensures authenticated communication with custom BackOfficeRoute controllers.

How do I generate a TypeScript client for an Umbraco backoffice API?

Generate a TypeScript client for an Umbraco backoffice API by exposing Swagger for your custom routes and using @hey-api/openapi-ts to generate type-safe methods from the swagger.json file. This enables reliable data integration.

Does Umbraco backoffice API communication require bearer token auth for extension development?

Yes, Umbraco backoffice API communication requires bearer token auth to avoid unauthorized failures. Extension development must consume the UMB_AUTH_CONTEXT to set base URLs and credentials for authenticated fetch calls to custom controllers.

What is the best way to configure authenticated API calls in Umbraco backoffice extensions?

The best way to configure authenticated API calls is setting the generated OpenAPI client's base URL and credentials using Umbraco's auth context in the extension entry point. This avoids unmaintainable, unsafe unauthenticated fetch calls.

Why does my unauthenticated fetch call fail when reading data from an Umbraco backoffice extension endpoint?

Unauthenticated fetch calls fail because they lack the required bearer token. Configure the OpenAPI client in your extension entry point using host.consumeContext(UMB_AUTH_CONTEXT, ...) to set baseUrl and credentials for authorized data access.