How-to › Authenticate and authorize calls

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.

Audience
API consumer
Level
intermediate
Topic
Send API keys and bearer tokens
Languages
TypeScript
Verified

Read first: Choose between header and query placement for an API key

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-rolled header on a plain HTTP clientA few calls, no generated client, one credentialEvery call site sets the header, so a scheme change means a search through the codeYou already ship a generated SDK
Kiota authentication providersA Kiota client, or a token that must be fetched per requestThe provider is your choice, so a scheme change in the document moves nothingYou want the document to decide the header
OpenAPI Generator typescript-fetch ConfigurationA client from a document that declares its schemesNo credential code at all when the document declares noneThe document has no securitySchemes and you cannot add them
sdkgen constructor credential optionsAn sdkgen client, a static key, or a token endpoint for refreshapikey takes a string only, so a rotating token needs an extend hook or the secrets featureYour calls go through direct(), which skips an extend hook
Speakeasy security option and callbackA Speakeasy SDK, with a function called on every requestNeeds a Speakeasy account to generate, and schemes in the documentYou 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.

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

  1. 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.name also removes a credential under the declared name, which keeps a request from carrying the credential twice. ↩︎ Back to text

  2. The OpenAPI 3.0.3 specification 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. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.