API Keys

The first matching method wins. This means if a request includes both a session cookie and an API key header, the cookie takes precedence.

Creating API keys

Via the Dashboard

Navigate to Settings > API Keys and click New API Key. You will need to:

1. Give the key a descriptive name (e.g. "ERP Sync - Production")
2. Select one or more roles that define the key's permissions
3. Click Create

The full API key will be displayed once. Copy it immediately or download the .env file — the secret cannot be retrieved later. If you lose it, you must rotate the key.

Via the Admin API

Using API keys

Send the API key in the vendure-api-key header:

Or in a Node.js script:

How API keys work

Understanding the internals helps when customizing or debugging API key authentication.

Key structure

An API key consists of two parts separated by a colon:

<lookupId>:<secret>

• Lookup ID (24 hex chars by default) — a non-secret identifier used to find the key in the database. Think of it like a username.
• Secret (64 hex chars by default) — the secret portion of the key. The full key (lookupId:secret) is hashed using bcrypt and stored in the database.

This two-part design is important: bcrypt produces different hashes for the same input (due to random salts), so you cannot look up a key by hashing the incoming secret and searching for a match. The lookup ID solves this by providing a stable, indexable identifier.

Authentication flow

When a request arrives with an API key:

1. The vendure-api-key header value is extracted
2. The key is parsed into lookupId and secret
3. The ApiKey entity is fetched from the database using the lookupId
4. The full incoming key (lookupId:secret) is verified against the stored bcrypt hash
5. The session associated with the key's user is loaded (or created if missing)
6. The request proceeds with that user's roles and permissions

Permissions and channels

Each API key is associated with a dedicated user that holds the key's roles. This user:

• Has no login credentials (cannot be used for interactive authentication)
• Is created automatically when the API key is created
• Is soft-deleted when the API key is deleted (the database row remains with a deletedAt timestamp)
• Has its permissions determined entirely by the assigned roles

The key also tracks an owner — the administrator who created it. This is useful for auditing.

API keys are channel-aware. When you create an API key in a specific channel context, it is scoped to that channel. The key's permissions only apply within its assigned channels, just like any other user in a multi-channel setup.

Real-world examples

ERP data sync

A common use case is synchronizing product and inventory data between Vendure and an ERP system:

Create an API key with a role that has ReadCatalog and UpdateCatalog permissions — nothing more.

Scheduled report generation

A cron job that generates daily sales reports:

Managing API keys

Rotating keys

If a key is compromised or as part of regular security hygiene, you can rotate it:

Rotation preserves the key's roles and permissions but generates a new secret. Any integration using the old key will immediately stop working.

Tracking usage

The lastUsedAt field on each API key tracks when it was last used for authentication. Use this to identify unused keys:

Keys that haven't been used in months are candidates for deletion.

Customizing the API key strategy

You can customize how API keys are generated, parsed, and hashed by providing a custom strategy.

Custom key format

For example, to use a prefix that identifies the key type:

This produces keys like adm_a1b2c3d4e5f6:xyz789....

Custom header name

If vendure-api-key conflicts with your infrastructure:

Tuning lastUsedAt updates

By default, lastUsedAt is updated on every request. For high-traffic API key usage, you can reduce database writes:

Troubleshooting

API key is ignored (cookie takes priority)

If you're testing in a browser-based tool (like the GraphQL playground at /admin-api), the browser sends a session cookie automatically. Since cookies are checked before API keys, the cookie wins and the key is ignored.

Fix: Use a tool that doesn't send cookies, such as curl or a standalone HTTP client. Alternatively, clear your browser cookies for the Vendure domain.

"Forbidden" error with valid key

If you get a Forbidden error despite having a valid API key:

1. Check that 'api-key' is included in the tokenMethod config
2. Verify the key's roles include the required permissions for the query you're running
3. Confirm the key hasn't been deleted or rotated

Key format errors

API keys must be in the format <lookupId>:<secret>. If the header value doesn't contain the delimiter (: by default), the key won't be parsed and the request will be unauthenticated.

Security best practices

1. Principle of least privilege — create keys with only the permissions needed. A data sync script that reads products should not have SuperAdmin access.
2. One key per integration — don't share keys across services. If one is compromised, you can rotate it without affecting others.
3. Store keys in environment variables — never commit API keys to source control. Use your hosting platform's secret management.
4. Rotate regularly — establish a rotation schedule, especially for keys with broad permissions.
5. Monitor usage — check lastUsedAt periodically. Delete keys that are no longer in use.
6. Use HTTPS — API keys are sent in headers. Without TLS, they can be intercepted in transit.