{"record":{"id":"0455d7731b437bce","repo":"immich-app/immich","slug":"the-api-key-header-can-only-be-set-using-setapikey","errorCode":null,"errorMessage":"The API key header can only be set using setApiKey().","messagePattern":"The API key header can only be set using setApiKey\\(\\)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/sdk/src/index.ts","lineNumber":47,"sourceCode":"};\n\nexport const setHeader = (key: string, value: string) => {\n  assertNoApiKey(key);\n  defaults.headers = defaults.headers || {};\n  defaults.headers[key] = value;\n};\n\nexport const setHeaders = (headers: Record<string, string>) => {\n  defaults.headers = defaults.headers || {};\n  for (const [key, value] of Object.entries(headers)) {\n    assertNoApiKey(key);\n    defaults.headers[key] = value;\n  }\n};\n\nconst assertNoApiKey = (headerKey: string) => {\n  if (headerKey.toLowerCase() === 'x-api-key') {\n    throw new Error('The API key header can only be set using setApiKey().');\n  }\n};\n\nexport const getAssetOriginalPath = (id: string) => `/assets/${id}/original`;\n\nexport const getAssetThumbnailPath = (id: string) => `/assets/${id}/thumbnail`;\n\nexport const getAssetPlaybackPath = (id: string) =>\n  `/assets/${id}/video/playback`;\n\nexport const getUserProfileImagePath = (userId: string) =>\n  `/users/${userId}/profile-image`;\n\nexport const getPeopleThumbnailPath = (personId: string) =>\n  `/people/${personId}/thumbnail`;\n","sourceCodeStart":29,"sourceCodeEnd":63,"githubUrl":"https://github.com/immich-app/immich/blob/199723261c6ffa897fec8ccdaea6359e39c37cc3/packages/sdk/src/index.ts#L29-L63","documentation":"The Immich SDK guards the x-api-key header so it can only be set through the dedicated setApiKey() (or init({ apiKey })) entry point. setHeader and setHeaders route every key through assertNoApiKey, which throws a plain Error when the lowercased key equals x-api-key. This prevents callers from accidentally bypassing the key-management path or overwriting the API key with an unrelated header value.","triggerScenarios":"Calling setHeaders({ 'x-api-key': '...' }), setHeaders({ 'X-API-KEY': '...' }), setHeader('X-Api-Key', value), or passing headers: { 'x-api-key': ... } to init(). The check is case-insensitive, so any capitalization triggers it.","commonSituations":"Migrating from a custom fetch wrapper where you set auth headers manually; copy-pasting a header object that includes the api key; trying to override the key per-request via setHeaders.","solutions":["Call setApiKey(apiKey) instead of setting the header yourself.","If using init(), pass the key via the apiKey field and keep headers free of x-api-key.","Filter the x-api-key key out of any dynamic header object before calling setHeaders."],"exampleFix":"// before\nsetHeaders({ 'x-api-key': apiKey, 'accept': 'application/json' });\n// after\nsetApiKey(apiKey);\nsetHeaders({ 'accept': 'application/json' });","handlingStrategy":"validation","validationCode":"// before calling setHeaders, strip any api-key variant\nconst SAFE_HEADERS = Object.fromEntries(\n  Object.entries(headers).filter(\n    ([k]) => k.toLowerCase() !== 'x-api-key',\n  ),\n);\nsetHeaders(SAFE_HEADERS);\nsetApiKey(apiKey);","typeGuard":"const isApiKeyHeader = (key: string): boolean =>\n  key.toLowerCase() === 'x-api-key';","tryCatchPattern":"try {\n  setHeaders(headers);\n} catch (e) {\n  if ((e as Error).message.includes('setApiKey')) {\n    setApiKey(headers['x-api-key']);\n    const { 'x-api-key': _omit, ...rest } = headers;\n    setHeaders(rest);\n  } else throw e;\n}","preventionTips":["Always set the API key via setApiKey / init({ apiKey }), never via setHeaders.","Treat the headers object as metadata-only and filter api-key variants before passing it in.","Centralize SDK init in one place so no other code touches headers directly."],"tags":["sdk","authentication","headers","configuration"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}