Skip to main content
Version: 2.x

QraftSecureRequestFn

The <QraftSecureRequestFn /> component is used to provide SecurityScheme handlers. These handlers extend the requestFn function to create a secured API client.

See the OpenAPI Authentication 🔗 specification for more information.

warning

This feature is still in the experimental stage 🧪 and may change in the future.

import { createAPIClient } from './api'; // generated by OpenAPI Qraft CLI
import { requestFn } from '@openapi-qraft/react';
import { QraftSecureRequestFn } from '@openapi-qraft/react/Unstable_QraftSecureRequestFn';

const QraftAPIClientContext = createContext<ReturnType<typeof createAPIClient>>(null!);

function App() {
  <QraftSecureRequestFn
    requestFn={requestFn}
    securitySchemes={securitySchemes}
  >
    {(secureRequestFn) => (
      <QraftAPIClientContext.Provider value={
        createAPIClient({ requestFn: secureRequestFn, baseUrl, queryClient })
      }>
        <MyApp />
      </QraftAPIClientContext.Provider>
    )}
  </QraftSecureRequestFn>
}

Properties​

  • requestFn: requestFn(requestScheme, requestInfo) => Promise<T> - Required requests function to be secured.
  • securitySchemes: { [key: string]: SecuritySchemeHandler } - Required. Handlers for security schemes used in secure requests.
    • Key: The name of the SecurityScheme.
    • Value: The corresponding SecuritySchemeHandler.
    • Note: You can specify multiple security scheme handlers. If an operation specifies multiple security schemes, the first defined handler will be used.
  • queryClient?: QueryClient - Optional QueryClient 🌴 to be used for security scheme handlers. This query client will not be used for usual requests, only for security scheme handlers.
tip

Under the hood, the QraftSecureRequestFn component handles initial auth request and updates the token if necessary. It automatically detects the JWT expiration, or you can specify the refresh using the refreshInterval property.

Security Scheme Handler​

A SecuritySchemeHandler is a function that returns a SecurityScheme object or a promise that resolves to it. Each handler must return specific data based on the security scheme type, which is used to authenticate requests.

function securitySchemeHandler(props: {
  isRefreshing: boolean;
  signal: AbortSignal;
}) : SecurityScheme | Promise<SecurityScheme>

Properties​

  • isRefreshing: boolean - A flag indicating whether the security scheme is being refreshed.
  • signal: AbortSignal - An optional AbortSignal to cancel the request. Usually, it is used to cancel the refresh request.

Returns​

The handler must return a SecurityScheme object or a promise that resolves to it. The SecurityScheme is a union of the following types:

type SecurityScheme =
  | SecuritySchemeBearer
  | SecuritySchemeBasic
  | SecuritySchemeAPIKey
  | SecuritySchemeCookie;

Supported Security Schemes​

Example​

In this example, the mySecurityScheme security scheme handler is used to obtain and refresh the JWT Bearer token:

import { QraftSecureRequestFn } from '@openapi-qraft/react/Unstable_QraftSecureRequestFn';
import { requestFn } from '@openapi-qraft/react';
import { createAPIClient } from './api'; // generated by OpenAPI Qraft CLI
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

import { useMemo, createContext, type ReactNode } from 'react';

const App = ({ children }: { children: ReactNode }) => {
  const queryClient = useMemo(() => new QueryClient(), []);

  return (
    <QueryClientProvider client={queryClient}>
      <QraftSecureRequestFn
        requestFn={requestFn}
        securitySchemes={{
          async mySecurityScheme({isRefreshing}) {
            return isRefreshing ? 'TEST_UNSECURE.NEW_BEARER.TOKEN' : 'TEST_UNSECURE.BEARER.TOKEN';
          }
        }}
      >
        {(secureRequestFn) => {
          // When using `secureRequestFn`, all requests that require the specified security scheme
          // will automatically include the appropriate authentication mechanism.
          //
          // For the `mySecurityScheme` security scheme, the initial request will use the provided token.
          // If the token needs refreshing (`isRefreshing` is true), a new token will be used.
          const api = createAPIClient({
            queryClient,
            requestFn: secureRequestFn,
            baseUrl: 'https://petstore3.swagger.io/api/v3',
          });

          return (
            <MyAPIContext.Provider value={api}>
              {children}
            </MyAPIContext.Provider>
          )
        }}
      </QraftSecureRequestFn>
    </QueryClientProvider>
  );
};

const MyAPIContext = createContext<ReturnType<typeof createAPIClient>>(null!);

export default App;