ApiKeyStrategy

Defines a custom strategy for how API-Keys get handled.

Defining different strategies between production-/ and development-environments and or differing strategies for Admin-/ and Customer-Users can be worthwhile to guarantee that API-Keys will never overlap.

Info

This is configured in either:

authOptions.adminApiKeyStrategy
authOptions.shopApiKeyStrategy

of your VendureConfig.

Signature

interface ApiKeyStrategy extends InjectableStrategy {    generateSecret(ctx: RequestContext): Promise<string>;    generateLookupId(ctx: RequestContext): Promise<string>;    hashingStrategy: PasswordHashingStrategy;    delimiter: string;    constructApiKey(lookupId: string, secret: string): string;    parse(token: string): ApiKeyStrategyParseResult;    lastUsedAtUpdateInterval: number | string;}

Extends: InjectableStrategy

generateSecret

method(ctx: RequestContext) => Promise<string>v3.6.0

Generates the API-Key secret which ultimately gets hashed and determines the session id.

generateLookupId

method(ctx: RequestContext) => Promise<string>v3.6.0

Generates an API-Key lookup ID.

A separate lookup ID enables us to use stronger salted hashing methods for the actual API-Key. This is because when we extract the incoming API-Key from the request, hashing methods that automatically handle salting (e.g. bcrypt) will produce different hashes for the same input, making it impossible to compare the incoming API-Key with the stored hash.

By using a separate lookup ID, we can identify the correct stored hash to compare against.

hashingStrategy

propertyPasswordHashingStrategyv3.6.0

Defines a custom strategy for how API-Keys get hashed and checked.

Performance Consideration

Vendure does not store API-Keys in plain text, but rather a hashed version of the key, similar to how passwords are handled. This means that when a request comes in with an API-Key, Vendure needs to hash the provided key and compare it with the stored hash. This means your hashing strategy must preferably be as fast as possible to avoid performance issues since hashing happens on every request that uses API-Key authorization.

delimiter

propertystring

Default:":"

Used when constructing and parsing API-Keys. You might need to override this delimiter if you customized the secret-/ and or lookup-generation. See constructApiKey or parse for more detailed information.

constructApiKey

method(lookupId: string, secret: string) => stringv3.6.0

Constructs an API-Key which the Users supply to the API.

Each strategy determines how it combines the lookup ID with the secret itself, because lookup-/ and secret-generation are customizable leading to Vendure not enforcing a fixed delimiter.

The output of this function must be parsable via this strategys parse function.

parse

method(token: string) => ApiKeyStrategyParseResultv3.6.0

In order to allow users to send only one header with their API-Key, while still supporting a separate lookup ID, strategies must be able to parse provided tokens into both parts, more specifically this function must be able to parse the output of constructApiKey.

We do not force an arbitrary delimiter, for example a colon ':', because the secret itself and the lookup ID are both customizable and may conflict with it, hence the need for custom parsing.

Custom parsing also allows strategies to use special characters in their API-Keys, by requiring the token to be base64 encoded for example or include prefixes such as:

'test_', 'prod_'
'admin_', 'customer_'

to visually distinguish between keys more easily.

lastUsedAtUpdateInterval

propertynumber | stringv3.6.0

Default:0

The main use of the lastUsedAt-field is enabling the detection and invalidation of unused API-Keys. By default, every request which gets authorized by an API-Key persists the usage date. This might not be desirable for larger instances, due to the cost of frequent database writes.

Defining a longer duration, for example 15 minutes, means that the lastUsedAt field will only be written to in 15 minute intervals, resulting in considerably fewer database writes. This technically reduces the accuracy of the lastUsedAt-field but keep in mind that when looking for unused keys, what often matters is that a key has been used at all in the last days or weeks and not the specific second.

If passed as a number should represent milliseconds and if passed as a string describes a time span per zeit/ms. Eg: 5m, '1 hour', '10h'

BaseApiKeyStrategy

@vendure/core Source

Intended to be extended by consumers of the ApiKeyStrategy if they do not require their own construction/parsing logic. Provides default implementations of constructApiKey, parse, delimiter, and lastUsedAtUpdateInterval.

Signature

class BaseApiKeyStrategy implements ApiKeyStrategy {    abstract hashingStrategy: PasswordHashingStrategy;    generateSecret(ctx: RequestContext) => Promise<string>;    generateLookupId(ctx: RequestContext) => Promise<string>;    delimiter = ':';    lastUsedAtUpdateInterval: ApiKeyStrategy['lastUsedAtUpdateInterval'] = 0;    constructApiKey(lookupId: string, secret: string) => string;    parse(token: string) => ApiKeyStrategyParseResult;}

Implements: ApiKeyStrategy

hashingStrategy

propertyPasswordHashingStrategy

generateSecret

method(ctx: RequestContext) => Promise<string>

generateLookupId

method(ctx: RequestContext) => Promise<string>

delimiter

property

lastUsedAtUpdateInterval

propertyApiKeyStrategy['lastUsedAtUpdateInterval']

constructApiKey

method(lookupId: string, secret: string) => string

parse

method(token: string) => ApiKeyStrategyParseResult

RandomBytesApiKeyStrategy

@vendure/core Sourcev3.6.0

A generation strategy that uses node:crypto to generate random hex strings for API-Keys via randomBytes.

This strategy defines API-Keys where both parts are the aforementioned random bytes like so:

Text

<lookupId>:<apiKey>

Note the colon ':' delimiter between the lookup ID and the api key.

Signature

class RandomBytesApiKeyStrategy extends BaseApiKeyStrategy {    readonly secretSize: number;    readonly lookupSize: number;    readonly hashingStrategy: PasswordHashingStrategy;    constructor(input?: RandomBytesApiKeyStrategyOptions)    generateSecret(ctx: RequestContext) => Promise<string>;    generateLookupId(ctx: RequestContext) => Promise<string>;}

Extends: BaseApiKeyStrategy

secretSize

propertynumber

lookupSize

propertynumber

hashingStrategy

propertyPasswordHashingStrategy

generateSecret

method(ctx: RequestContext) => Promise<string>

generateLookupId

method(ctx: RequestContext) => Promise<string>

Was this chapter helpful?

Report Issue

Edited Apr 20, 2026·Edit this page