On handling authentication

[dasdawidt]

Hello everyone!

In my team we use OpenAPI Security Schemes for defining different authentication methods for our endpoints. We are currently figuring out how to generate clients for using endpoints with auth.

Currently, our best approach is to create a helper function that builds and returns a RequestConfig & { client: Client } object, the client being a wrapper function around the fetch client that comes with @kubb/plugin-client. This works pretty well and we don't need to re-implement everything that is already included in the fetch client (as we would need to when implementing our own client).

However, when it comes to auth this gets a little difficult as not all our endpoint require (the same) auth. For example, imagine three endpoints:

• Endpoint A (requires no auth)
• Endpoint B (required OIDC auth)
• Endpoint C (requires API key auth)

Now the client needs some way to know which headers to append to which request. As far as I know, there is no way to know inside the fetch function (based on the params) whether this path requires auth (e.g. has a securityScheme associated with it). Maybe there would be a way using generators or custom plugins.

I know that other solutions such as Hey API have a concept for auth or alternativeley offer the option to register interceptors (which would make our wrapper function obsolete).

Are there any existring solutions for this problem? I guess there are already plans to implement similar options, as "make the client smarter" is part of the roadmap?

[dosubot[bot]]

Hi @dasdawidt! I'm Dosu and I’m helping the kubb team.

Great question! Currently, Kubb doesn't automatically process OpenAPI security schemes during code generation, so there's no built-in way for the generated client to know which endpoints require which auth method. Authentication is treated as a runtime concern rather than a codegen feature.

That said, here are a few approaches that might help your use case:

1. Use the Axios client with interceptors

If you switch to the axios client, you get access to axiosInstance which supports interceptors natively—similar to what Hey API offers:

import { axiosInstance } from '@kubb/plugin-client/clients/axios'

axiosInstance.interceptors.request.use((config) => {
  // Route auth based on URL or custom logic
  if (config.url?.includes('/public')) {
    // No auth
  } else if (config.url?.includes('/admin')) {
    config.headers['X-API-Key'] = getApiKey()
  } else {
    config.headers.Authorization = `Bearer ${getBearerToken()}`
  }
  return config
})

2. Use importPath for a custom client

The importPath option lets you provide your own client implementation where you can build in whatever auth logic you need, including routing based on endpoint patterns.

3. Injectable client parameter

Recent updates allow you to pass a custom client function per-request via the config parameter, which could help for mixed auth scenarios.

As for the roadmap—the v5 roadmap mentions "make the client smarter" but doesn't currently include automatic security scheme handling. This could be a good feature request though, since the underlying @kubb/oas package already parses the security scheme definitions from OpenAPI specs—they're just not used during generation yet.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[dasdawidt]

@dosu Thanks for the overview! How could it be possible to extend the generated code to get access to the securitySchemes inside the fetch function (i.e. know "this call requires this security scheme")?

[dosubot[bot]]

You can achieve this using Kubb's custom generator system. The key is that security requirements are accessible via operation.schema.security during code generation.

Here's a sketch of how you'd create a custom generator that injects security metadata:

import { createReactGenerator } from '@kubb/plugin-oas/generators'

export const securityClientGenerator = createReactGenerator({
  name: 'security-client',
  Operation({ operation, generator }) {
    const oas = generator.context.oas
    
    // Access security requirements from the operation
    const securityReqs = operation.schema.security || []
    const securitySchemes = oas.api.components?.securitySchemes || {}
    
    // Build security metadata
    const securityMeta = securityReqs.map(req => {
      const schemeName = Object.keys(req)[0]
      const scheme = securitySchemes[schemeName]
      return {
        name: schemeName,
        type: scheme?.type,
        scopes: req[schemeName]
      }
    })
    
    // Generate client code with security info attached
    return (
      <File /* ... */>
        <Function name={operationName} export async>
          {`
            return client({
              method: '${operation.method}',
              url: '${operation.path}',
              _security: ${JSON.stringify(securityMeta)}
            })
          `}
        </Function>
      </File>
    )
  }
})

Then register it in your config:

pluginClient({
  generators: [securityClientGenerator]
})

The clientStaticGenerator example shows a similar pattern where metadata (method, url, operationId) is added to generated functions. You'd follow the same approach but add security info instead.

Your custom client implementation can then read the _security field and apply the appropriate auth headers based on the scheme type.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.