Bearer Token Authentication

The SecuritySchemeBearer type supports bearer token authentication, commonly used with JWT tokens. It can either be a simple string representing the JWT token or an object with additional metadata if another token format is used.

See the OpenAPI Bearer Authentication 🔗 specification for more information.

type SecuritySchemeBearer =
  | string /** JWT Bearer token **/
  | {
      /** Refresh interval in milliseconds. */
      refreshInterval: number;
      /** Token to be used for authentication. */
      token: string;
    };

• String: A simple JWT Bearer token string.
  • The JWT must include the exp (expiration time) and iat (issued at) fields.
  • QraftSecureRequestFn will automatically refresh the token if it expires.
  • If the exp and iat fields are not present, an object token format must be used; otherwise, an error will be thrown.
• Object: An object containing:
  • refreshInterval: The interval (in milliseconds) at which the token should be refreshed.
  • token: The JWT token to be used for authentication.

Examples

JWT Bearer

When providing a simple JWT Bearer token string, the token will be used as is. QraftSecureRequestFn will refresh the token if it expires based on the exp (expiration time) and iat (issued at) fields.

In this example, the clientToken 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={{
          clientToken: async ({ isRefreshing }) => {
            const api = createAPIClient({
              requestFn,
              baseUrl: 'https://petstore3.swagger.io/api/v3',
            });

            if (!isRefreshing) {
              const { access_token } = await api.auth.obtainToken({
                body: {
                  grant_type: 'client_credentials', // specify `body` or `parameters` if needed
                },
              });

              // If token is JWT Bearer, return the token string
              // The token will be used in the `Authorization: Bearer <token>` header
              return access_token;
            }

            const { access_token } = await api.auth.refreshToken({
              body: {
                grant_type: 'client_credentials', // specify `body` or `parameters` if needed
              },
            });

            return access_token;
          }
        }}
      >
        {(secureRequestFn) => {
          // When using `secureRequestFn`, all requests that require the `clientToken` security scheme
          // will automatically include the `Authorization: Bearer <token>` header.
          // This ensures that these requests are authenticated with the provided JWT token.
          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;

Custom Token

In case the token format is different from the standard JWT Bearer token, you can provide an object with refreshInterval and token properties.

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={{
          clientToken: async ({ isRefreshing }) => {
            const api = createAPIClient({
              queryClient,
              requestFn,
              baseUrl: 'https://petstore3.swagger.io/api/v3',
            });

            if (!isRefreshing) {
              // Use Qraft's built-in Vanilla operation methods to fetch the token
              const { access_token, expires_in } = await api.auth.obtainToken({
                body: {
                  grant_type: 'client_credentials', // specify `body` or `parameters` if needed
                },
              }, requestFn);

              return {
                refreshInterval: expires_in * 1000, // specify the refresh interval in milliseconds
                token: access_token, // specify the token to be used in the `Authorization: Bearer <token>` header
              };
            }

            const { access_token, expires_in } = await api.auth.refreshToken({
              body: {
                grant_type: 'client_credentials',
              },
            }, requestFn);

            return {
              refreshInterval: expires_in * 1000,
              token: access_token,
            };
          }
        }}
      >
        {(secureRequestFn) => {
          // When using `secureRequestFn`, all requests that require the `clientToken` security scheme
          // will automatically include the `Authorization: Bearer <token>` header.
          // This ensures that these requests are authenticated with the provided JWT token.
          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;