# How to hand a generated SDK its credential instead of a header

> Pass an API key or token through the client's own options, let the generated code place it from the security schemes, and check the header on a local server.

Source: https://voxgig.com/howto/credential-options-in-a-generated-sdk

- Audience: api-consumer
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

Give the key to the option the generator made from securitySchemes: apikey in an sdkgen client, security in a Speakeasy one, apiKey or accessToken in OpenAPI Generator's Configuration, or an auth provider in Kiota. The scheme decides the header and prefix. Without one, sdkgen sends the bare key as Authorization and OpenAPI Generator sends nothing, so fix the document or the project overlay, not the generated code.

---
## You will need

Node 22 or later, an OpenAPI 3 document with `securitySchemes`, and a generated SDK from any of
the generators compared. Verified 2026-11-21 against Node 22.23.5. A scheme names an `apiKey` with
its `in` and `name`, or an `http` scheme such as `bearer`, as the
[OpenAPI 3.0.3 specification](https://spec.openapis.org/oas/v3.0.3) defines.[^1] Where the key
should travel is a separate choice, covered in
[choose between header and query placement for an API key](/howto/header-or-query-api-key-placement).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Hand-rolled header on a plain HTTP client](https://developer.mozilla.org/en-US/docs/Web/API/Headers) | A few calls, no generated client, one credential | Every call site sets the header, so a scheme change means a search through the code | You already ship a generated SDK |
| [Kiota authentication providers](https://learn.microsoft.com/en-us/openapi/kiota/authentication) | A Kiota client, or a token that must be fetched per request | The provider is your choice, so a scheme change in the document moves nothing | You want the document to decide the header |
| [OpenAPI Generator `typescript-fetch` Configuration](https://openapi-generator.tech/docs/generators/typescript-fetch/) | A client from a document that declares its schemes | No credential code at all when the document declares none | The document has no `securitySchemes` and you cannot add them |
| [sdkgen constructor credential options](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | An sdkgen client, a static key, or a token endpoint for refresh | `apikey` takes a string only, so a rotating token needs an `extend` hook or the `secrets` feature | Your calls go through `direct()`, which skips an `extend` hook |
| [Speakeasy security option and callback](https://www.speakeasy.com/docs/sdks/customize/authentication/security-callbacks) | A Speakeasy SDK, with a function called on every request | Needs a Speakeasy account to generate, and schemes in the document | You cannot send the document to a hosted tool |

Voxgig maintains sdkgen, which is one of the five rows and is not the recommendation.

The generated rows move the header when the document changes, and the hand-rolled row does not.
Kiota sits between them: its generated code came out the same for all three documents, so the
header is whatever provider you wire, which keeps working when the document is wrong.

## Send one key through three generated clients

`headers.mjs` runs one list call per client against a stand-in on `127.0.0.1` that wants a bearer
token for the first document and `X-API-Key` for the second. The clients were generated from
three variants of one Bookshelf document, and each got `sk-test-1` through its own options:

```bash
node headers.mjs
```

```text output
api-none.json: declares no scheme; the API wants Authorization: Bearer
  sdkgen             apikey: 'sk-test-1'                    authorization: sk-test-1         401
  OpenAPI Generator  Configuration({ apiKey, accessToken }) (no credential header)           401
  Kiota              BaseBearerTokenAuthenticationProvider  authorization: Bearer sk-test-1  200
api-apikey.json: declares apiKey in the X-API-Key header
  sdkgen             apikey: 'sk-test-1'                    x-api-key: sk-test-1             200
  OpenAPI Generator  Configuration({ apiKey, accessToken }) x-api-key: sk-test-1             200
  Kiota              ApiKeyAuthenticationProvider           x-api-key: sk-test-1             200
api-bearer.json: declares http bearer
  sdkgen             apikey: 'sk-test-1'                    authorization: Bearer sk-test-1  200
  OpenAPI Generator  Configuration({ apiKey, accessToken }) authorization: Bearer sk-test-1  200
  Kiota              BaseBearerTokenAuthenticationProvider  authorization: Bearer sk-test-1  200
```

With a scheme declared, the sdkgen and OpenAPI Generator clients followed it with no code from
the caller. Without one, they split: sdkgen 4.44.3 still took `apikey` and sent it bare as
`authorization`, and OpenAPI Generator ignored both options.

## Read the option names from the generated files

The option names come from the model, so read them from what was generated rather than from a
guess.[^2] `surface.mjs` reads the committed output:

```bash
node surface.mjs
```

```text output
                                        api-none.json     api-apikey.json   api-bearer.json
sdkgen Config.js auth                   (no auth block)   name X-API-Key    prefix Bearer
sdkgen REFERENCE.md lists apikey        no                yes               yes
OpenAPI Generator credential reads      0                 10                10
Kiota: 4 generated files, identical for all three documents: true
```

The sdkgen `REFERENCE.md` lists `options.apikey` only when the document declares a scheme, though
the constructor accepts it either way. Its constructor also takes `auth: { name, prefix }`, which
the [model reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) describes
as read on every request, so you can rename the header without regenerating. Repeated on sdkgen 4.45.0,
the no-scheme build still sent the key bare as `authorization` and still left `apikey` out of
`REFERENCE.md`.

## Follow a rotating token

A string set in a constructor cannot follow a token that changes. `rotate.mjs` rotates the token
after the second of three calls:

```bash
node rotate.mjs
```

```text output
the token rotates after the second call
  sdkgen apikey: 'tok-1'           tok-1 200, tok-1 200, tok-1 401
  sdkgen secrets exchange          (bought), tok-1 200, tok-1 200, tok-1 401, (bought), tok-2 200
  sdkgen extend, PreRequest        tok-1 200, tok-1 200, tok-2 200
  OpenAPI Generator accessToken()  tok-1 200, tok-1 200, tok-2 200
  Kiota AccessTokenProvider        tok-1 200, tok-1 200, tok-2 200
sdkgen apikey given a function: Expected field apikey to be string, but found function: __STRINGIFY_FAILED__.
```

OpenAPI Generator's `accessToken` and Kiota's `getAuthorizationToken` are functions called per
request, so they read the current token. sdkgen refuses a function for `apikey` and offers two
other routes. An object in the constructor's `extend` list runs at `PreRequest` on every entity
call, after the headers are built, so it can set the current token:

```js title="rotate.mjs"
  await run('sdkgen extend, PreRequest', (api) => {
    const token = { name: 'token', PreRequest(ctx) { ctx.spec.headers.authorization = `Bearer ${api.store.current}` } }
    const c = new None({ base: api.base, extend: [token] })
```

A test shows that `direct()` calls skip the hook. The other route is the `secrets` feature, which the
[features reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md)
documents. Switched on in `project.aontu` and in the constructor's `feature` options, it posts a
refresh token to `auth/token`, and on a 401 buys another token and retries once.

```aontu title="sdk-model/bearer.project.aontu"
main: kit: feature: secrets: active: true
```

## Set the same credential in Speakeasy and Kiota

Speakeasy builds its `security` option from `securitySchemes`, according to its
[authentication overview](https://www.speakeasy.com/docs/sdks/customize/authentication/overview).
For one bearer scheme named `auth`, its
[simple schemes page](https://www.speakeasy.com/docs/sdks/customize/authentication/simple-schemes)
shows `new SDK({ auth: "<YOUR_BEARER_TOKEN_HERE>" })`, adding the `Bearer` prefix when it is
missing. For a rotating token, its security callbacks page passes `security` an async function that
returns `{ bearerAuth: token }`, which it says is called whenever a request is made. Speakeasy's
CLI needs a login to a Speakeasy account, as its
[getting started page](https://www.speakeasy.com/docs/speakeasy-reference/cli/getting-started)
says, so it was not run here. Neither authentication page says what a document with no scheme
produces; add the scheme to the document.

Kiota generated the same four source files for all three documents; only `kiota-lock.json`,
which records the document's path and hash, differs. The caller picks the provider:
`ApiKeyAuthenticationProvider` takes the key, the header name, and a location, and
`BaseBearerTokenAuthenticationProvider` asks an access token provider for each request, as the
[Kiota authentication page](https://learn.microsoft.com/en-us/openapi/kiota/authentication)
describes. That suits a team whose documents are wrong more often than their code.

## Check it worked

Nine tests hold the claims, each against the stand-in: the three documents, the rotation, the
`extend` hook and `direct()`, the fixes below, and the Kiota host check.

```bash
node --test credential.test.mjs
```

```text output
1..9
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1108.80226
```

## When it goes wrong

Every call returns 401, and the server logs `authorization: sk-test-1` with no prefix. The
document declares no scheme. Fix it without touching generated code: pass
`auth: { prefix: 'Bearer' }` to the sdkgen constructor, or set `config: auth` in `project.aontu`
and regenerate. For OpenAPI Generator, add `securitySchemes`, or pass `headers` in `Configuration`.

```aontu title="sdk-model/fix.project.aontu"
main: kit: config: auth: { active: true, prefix: 'Bearer' }
```

```bash
node fix.mjs
```

```text output
sdkgen constructor auth: { prefix: 'Bearer' }    200  authorization: Bearer sk-test-1
sdkgen project.aontu config auth, regenerated    200  authorization: Bearer sk-test-1
OpenAPI Generator Configuration({ headers })     200  authorization: Bearer sk-test-1
```

The token reaches a host it was never meant for. Kiota's `AllowedHostsValidator` allows every host
when its set is empty, and the provider in `clients.mjs` decides per URL. Give it the API's hosts;
a test shows the token withheld from any other.

## When not to do this

Do not patch a generated file to add a prefix. The patch is lost on the next generate, while the
constructor's `auth` option or the project overlay survives it.

Do not pick sdkgen for a credential your code mints per request if the code calls `direct()`.
Its `apikey` takes a string, and the `extend` hook that can set a token per request does not run
for `direct()`. Speakeasy is the
better fit when you generate there already and want a callback in every language it supports.
Kiota suits a team that wires authentication in code anyway, because its client keeps working
while the document's schemes are missing or wrong.

Do not read the header from a generator's README alone. sdkgen's README omits `apikey` for a
document with no scheme, and its constructor still sends one.

## Related how-tos

- [Choose between header and query placement for an API key](/howto/header-or-query-api-key-placement)

- [Design an SDK constructor that takes configuration once](/howto/sdk-client-constructor-and-configuration)

- [Inject a per-request credential into a generated SDK](/howto/per-request-credential-hook-in-a-generated-sdk)

- [Refresh an access token once under concurrent requests](/howto/refresh-a-token-once-under-concurrent-requests)

- [Add a bearer token to fetch without a client library](/howto/bearer-token-fetch-wrapper)

## Last verified

Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3 and
4.45.0, @voxgig/apidef 8.32.4, OpenAPI Generator 7.27.0, Kiota 1.39.0 with
`@microsoft/kiota-bundle` 1.0.0-preview.113, and TypeScript 5.9.3. Every output block is what the
command preceding it printed. The three generators that ran did so once, in `generate.sh`, and what
they wrote is committed under `generated/`. Speakeasy was not run, so its `security` option and its callback
are written as its documentation writes them.

[^1]: [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750.html), from October 2012, defines three
ways to send a bearer token and says a client MUST NOT use more than one in a request. The third,
a query parameter, is in the document to record current use, and the RFC adds that its use is
not recommended. sdkgen's
[model reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) says a
renamed `auth.name` also removes a credential under the declared name, which keeps a request
from carrying the credential twice.

[^2]: The [OpenAPI 3.0.3 specification](https://spec.openapis.org/oas/v3.0.3) makes an `http`
scheme name its Authorization scheme and asks for a value from the IANA registry. It also offers
`bearerFormat`, a hint it calls primarily for documentation purposes. None of the three documents
sets a `bearerFormat`, so the `Bearer` that the sdkgen and OpenAPI Generator builds of the third
document send came from `scheme: bearer` alone.