Your API wants Authorization: Bearer <key>, and the generated client answers every call with
401. Its OpenAPI document declares no security scheme, so one generator sends the key with no
prefix and another sends no header at all. Someone patches the generated file to add the prefix,
and the next regeneration removes the patch.
What you get
You will end up with a credential that each generated client places by itself, a local check of the exact header and prefix, and a token that can rotate. This is for you if you call an API through a generated SDK and want the key out of hand-set headers.
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 defines.1 Where the key
should travel is a separate choice, covered in
choose between header and query placement for an API key.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Hand-rolled header on a plain HTTP client | 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 | 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 | 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 | 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 | 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:
node headers.mjs
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:
node surface.mjs
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 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:
node rotate.mjs
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:
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
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.
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.
For one bearer scheme named auth, its
simple schemes page
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
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
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.
node --test credential.test.mjs
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.
main: kit: config: auth: { active: true, prefix: 'Bearer' }
node fix.mjs
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
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.
Footnotes
-
RFC 6750, 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 says a renamed
auth.namealso removes a credential under the declared name, which keeps a request from carrying the credential twice. ↩︎ Back to text -
The OpenAPI 3.0.3 specification makes an
httpscheme name its Authorization scheme and asks for a value from the IANA registry. It also offersbearerFormat, a hint it calls primarily for documentation purposes. None of the three documents sets abearerFormat, so theBearerthat the sdkgen and OpenAPI Generator builds of the third document send came fromscheme: beareralone. ↩︎ Back to text