Umbraco and Bellissima: Swagger, Tokens, Entry Points

The following examples are tested in Umbraco 14 and 15 and I have written them here mostly to be able to quickly look up how to generate a TypeScript client and get the access_token from Umbraco.

Basic authentication

In essence, we want to put the Authorization header in a fetch() call:

fetch('/myapi/controller/endpoint', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer 123' // <-- Token goes here
  }
});

This can be wrapped in Umbraco using the Context API:

/**
 * Make an authorized request to any Backoffice API.
 * @param host A reference to the host element that can request a context.
 * @param url The URL to request.
 * @param method The HTTP method to use.
 * @param body The body to send with the request (if any).
 * @returns The response from the request as JSON.
 */
async function makeRequest(host: UmbClassInterface, url: string, method = 'GET', body?: any) {
  const authContext = await host.getContext(UMB_AUTH_CONTEXT);
  const token = await authContext.getLatestToken();
  const response = await fetch(url, {
    method,
    body: body ? JSON.stringify(body) : undefined,
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
  });
  return response.json();
}

Don't do this, though. Use a TypeScript client generator instead:

TypeScript Client

I always use the latest version of @hey-api/openapi-ts to generate the TypeScript client. This library supports several clients, and I am trying to upgrade to their own @hey-api/client-fetch, but it also has a native fetch. Here is how to hook on to Umbraco's authentication for both clients.

First, install @hey-api/openapi-ts:

npm i --save @hey-api/openapi-ts @hey-api/client-fetch

Then create a script in package.json:

{
  "scripts": {
    "generate": "openapi-ts -i http://localhost:7029/umbraco/swagger/bellissima-v1/swagger.json?urls.primaryName=Bellissima%20Management%20Api -o src/api -c @hey-api/client-fetch"
  }
}

Next, create /App_Plugins/MyExtensions/umbraco-package.json and register an extension of the type backofficeEntryPoint:

{
  "name": "My Extensions",
  "alias": "My.Extensions",
  "version": "1.0.0",
  "extensions": [
    {
      "type": "backofficeEntryPoint",
      "alias": "My.Entrypoint",
      "name": "My Entrypoint",
      "js": "/App_Plugins/MyExtensions/entry-point.js"
    }
  ]
}

Make sure to set up a TypeScript transpiler (tsc, vite, etc) and create a entry-point.ts file.

@hey-api/client-fetch

Add the following to entry-point.ts:

import type { UmbEntryPointOnInit } from '@umbraco-cms/backoffice/extension-api';
import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth';
import { client } from './api/index.js';

export const onInit: UmbEntryPointOnInit = (host) => {
  host.consumeContext(UMB_AUTH_CONTEXT, (authContext) => {

    // Get API config
    const config = authContext.getOpenApiConfiguration();

    // Set base config
    client.setConfig({
      baseUrl: config.base,
      credentials: config.credentials
    });

    // Set interceptor to add authorization
    client.interceptors.request.use(async (req) => {
      const token = await config.token();
      if (token) {
        req.headers.set('Authorization', `Bearer ${token}`);
      }
      return req;
    });
  });
};

legacy/fetch

Note: This client is deprecated. To use it, replace @hey-api/client-fetch with legacy/fetch in the generate script.

Add the following to entry-point.ts:

import type { UmbEntryPointOnInit } from '@umbraco-cms/backoffice/extension-api';
import { UMB_AUTH_CONTEXT } from '@umbraco-cms/backoffice/auth';
import { OpenAPI } from './api/index.js';

export const onInit: UmbEntryPointOnInit = (host) => {
  host.consumeContext(UMB_AUTH_CONTEXT, (authContext) => {

    // Get API config
    const config = authContext.getOpenApiConfiguration();

    // Set base config
    OpenAPI.BASE = config.base;
    OpenAPI.TOKEN = config.token;
    OpenAPI.CREDENTIALS = config.credentials;
    OpenAPI.WITH_CREDENTIALS = config.withCredentials;
    OpenAPI.ENCODE_PATH = config.encodePath;
  });
};

The entry point ensures authorization is set up before any requests are made in the Backoffice, and you can now import the generated SDK and call it from any element with or without the tryExecute and tryExecuteAndNotify functions.