Skip to main content
Version: 1.x

QraftSecureRequestFn

The <QraftSecureRequestFn /> component is used to provide SecurityScheme handlers. These handlers extend the requestFn function, which can then be used with QraftContext to make secure requests.

See the OpenAPI Authentication 🔗 specification for more information.

warning

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

import { requestFn } from '@openapi-qraft/react';
import { QraftSecureRequestFn } from '@openapi-qraft/react/Unstable_QraftSecureRequestFn';

<QraftSecureRequestFn
  requestFn={requestFn}
  securitySchemes={securitySchemes}
  queryClient={queryClient}
>
  {(secureRequestFn) => (
    <QraftContext.Provider
      value={{
        requestFn: secureRequestFn,
        ...qraftContextValue,
      }}
    >
      {children}
    </QraftContext.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 { ReactNode } from 'react';
import { requestFn, QraftContext } from '@openapi-qraft/react';
import { QraftSecureRequestFn } from '@openapi-qraft/react/Unstable_QraftSecureRequestFn';

const App = ({ children }: { children: ReactNode }) => {
  return (
    <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.
        <QraftContext.Provider value={{ requestFn: secureRequestFn }}>
          {children}
        </QraftContext.Provider>
      )}
    </QraftSecureRequestFn>
  );
};

export default App;