@medusajs/api-key 2.22.0-snapshot-20261020204851 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +75 -0
  2. package/README.md +72 -1
  3. package/package.json +8 -4
package/AGENTS.md ADDED
@@ -0,0 +1,75 @@
1
+ # @medusajs/api-key
2
+
3
+ API Key Module (`Modules.API_KEY`, container key `"api_key"`). Stores publishable keys (`pk_...`, used by storefronts to scope requests to sales channels) and secret keys (`sk_...`, used to authenticate admin API requests).
4
+
5
+ ## Using this package
6
+
7
+ - Registered by default via `defineConfig` as `@medusajs/medusa/api-key` (a re-export of this package). No module options.
8
+ - Resolve: `container.resolve(Modules.API_KEY)` (type `IApiKeyModuleService` from `@medusajs/framework/types`).
9
+ - Prefer the core-flows workflows over calling the service directly from routes: `createApiKeysWorkflow`, `updateApiKeysWorkflow`, `revokeApiKeysWorkflow`, `deleteApiKeysWorkflow`, `linkSalesChannelsToApiKeyWorkflow` (`@medusajs/medusa/core-flows`).
10
+
11
+ ```ts
12
+ const apiKeyModule = container.resolve(Modules.API_KEY)
13
+
14
+ const key = await apiKeyModule.createApiKeys({
15
+ title: "Storefront",
16
+ type: "publishable",
17
+ created_by: userId,
18
+ })
19
+
20
+ await apiKeyModule.revoke(key.id, { revoked_by: userId, revoke_in: 3600 })
21
+ const matched = await apiKeyModule.authenticate("sk_...") // ApiKeyDTO | false
22
+ ```
23
+
24
+ ### Data model
25
+
26
+ - `ApiKey` (`apk_` prefix): `token`, `salt`, `redacted`, `title`, `type` (`"publishable" | "secret"`), `last_used_at`, `created_by`, `revoked_by`, `revoked_at`. Unique index on `token`.
27
+
28
+ ### Custom (non-generated) service methods
29
+
30
+ - `createApiKeys` / `upsertApiKeys`: generate the token; the raw token is returned only in this response.
31
+ - `updateApiKeys(idOrSelector, data)`: only `title` is persisted; other fields are ignored.
32
+ - `revoke(idOrSelector, { revoked_by, revoke_in? })`: sets `revoked_at` to now + `revoke_in` seconds.
33
+ - `authenticate(token)`: matches an unrevoked secret key; used by the framework `authenticate` middleware for `Authorization: Basic <sk_... or base64>` headers.
34
+ - `deleteApiKeys`: overridden to block deleting unrevoked keys.
35
+ - `retrieveApiKey`, `listApiKeys`, `listAndCountApiKeys`: overridden to blank `token` for secret keys and strip `salt`.
36
+
37
+ ### Events
38
+
39
+ No event constants; generated mutations emit internal events named `api_key.api-key.<created|updated|deleted|restored>` (see `MedusaService.interceptEntityMutationEvents`).
40
+
41
+ ### Module links
42
+
43
+ - `ApiKey` <-> `SalesChannel` (`link-modules/src/definitions/publishable-api-key-sales-channel.ts`): `api_key.sales_channels` / `sales_channel.publishable_api_keys`. The joiner config adds a legacy linkable key `publishable_key_id`.
44
+
45
+ ### Docs
46
+
47
+ - https://docs.medusajs.com/resources/commerce-modules/api-key.md
48
+ - https://docs.medusajs.com/resources/commerce-modules/api-key/concepts.md
49
+ - https://docs.medusajs.com/resources/commerce-modules/api-key/links-to-other-modules.md
50
+ - https://docs.medusajs.com/resources/commerce-modules/api-key/workflows.md
51
+
52
+ ## Architecture
53
+
54
+ - `src/services/api-key-module-service.ts`: the whole module. Extends `MedusaService({ ApiKey })` and overrides most generated methods (hence the `@ts-expect-error` signatures).
55
+ - Publishable keys: `"pk_" + 32 random bytes hex`, stored unhashed, empty `salt`.
56
+ - Secret keys: `"sk_" + 32 random bytes hex`, stored as `scrypt(token, salt, 64)` hex with a random 16-byte salt.
57
+ - `redacted` = first 6 chars + `***` + last 3 chars; used to narrow candidates before hashing in `authenticate_`.
58
+
59
+ ## Development
60
+
61
+ ```bash
62
+ yarn build
63
+ yarn test # src unit tests (only a noop)
64
+ yarn test:integration # integration-tests/__tests__/api-key-module-service.spec.ts (needs Postgres: DB_HOST, DB_USERNAME, DB_PASSWORD)
65
+ yarn test:integration -t "<test name>"
66
+ yarn migration:create # after any change to src/models; never hand-write migrations
67
+ ```
68
+
69
+ ## Gotchas
70
+
71
+ - Raw secret tokens are unrecoverable after creation: `list`/`retrieve` return `token: ""` for secret keys. Publishable key tokens are returned in full.
72
+ - `deleteApiKeys` throws `NOT_ALLOWED` unless every key is revoked, i.e. `revoked_at` is set and in the past. A key revoked with a future `revoke_in` cannot be deleted yet.
73
+ - `revoke` requires `revoked_by` and throws `INVALID_DATA` if any targeted secret key is already revoked.
74
+ - `omitToken` mutates the entity in place (MikroORM relies on non-enumerable fields for serialization); don't swap it for a spread copy.
75
+ - `authenticate` only considers `type: "secret"` keys; it never matches publishable keys.
package/README.md CHANGED
@@ -1 +1,72 @@
1
- # API Key Module
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/api-key
12
+ </h1>
13
+
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ API Key Module for Medusa: manages publishable and secret API keys, including creating, revoking, and authenticating them. Publishable keys scope storefront requests (for example, to sales channels), and secret keys authenticate admin API requests. It ships with `@medusajs/medusa` and is registered by default, so you normally use it through the Medusa application rather than installing it directly.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/api-key` |
44
+ | Type | Commerce Module |
45
+ | Module key | `Modules.API_KEY` (`"api_key"`) |
46
+ | Registered by default | Yes |
47
+ | Import from | `@medusajs/medusa/api-key` |
48
+
49
+ ## Features
50
+
51
+ - Create `publishable` and `secret` API keys.
52
+ - Revoke keys and authenticate requests with a key's token.
53
+
54
+ ## Installation
55
+
56
+ No installation needed. The module ships with `@medusajs/medusa` and is registered by default.
57
+
58
+ ## Usage
59
+
60
+ Resolve the module's service from the container, for example in a workflow step:
61
+
62
+ ```ts
63
+ import { Modules } from "@medusajs/framework/utils"
64
+
65
+ const apiKeyModuleService = container.resolve(Modules.API_KEY)
66
+ ```
67
+
68
+ ## Resources
69
+
70
+ - [API Key Module](https://docs.medusajs.com/resources/commerce-modules/api-key)
71
+ - [API Key concepts](https://docs.medusajs.com/resources/commerce-modules/api-key/concepts)
72
+ - [Commerce Modules](https://docs.medusajs.com/learn/fundamentals/modules/commerce-modules)
package/package.json CHANGED
@@ -1,15 +1,19 @@
1
1
  {
2
2
  "name": "@medusajs/api-key",
3
- "version": "2.22.0-snapshot-20261020204851",
3
+ "version": "2.22.0",
4
4
  "description": "Medusa API Key module",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "files": [
8
8
  "dist",
9
+ "AGENTS.md",
9
10
  "!dist/**/__tests__",
10
11
  "!dist/**/__mocks__",
11
12
  "!dist/**/__fixtures__"
12
13
  ],
14
+ "llms": "https://docs.medusajs.com/llms.txt",
15
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
16
+ "mcpServer": "https://docs.medusajs.com/mcp",
13
17
  "engines": {
14
18
  "node": ">=22.22.0"
15
19
  },
@@ -39,10 +43,10 @@
39
43
  "orm:cache:clear": "MIKRO_ORM_CLI_CONFIG=./mikro-orm.config.dev.ts MIKRO_ORM_ALLOW_GLOBAL_CLI=true medusa-mikro-orm cache:clear"
40
44
  },
41
45
  "devDependencies": {
42
- "@medusajs/framework": "2.22.0-snapshot-20261020204851",
43
- "@medusajs/test-utils": "2.22.0-snapshot-20261020204851"
46
+ "@medusajs/framework": "2.22.0",
47
+ "@medusajs/test-utils": "2.22.0"
44
48
  },
45
49
  "peerDependencies": {
46
- "@medusajs/framework": "2.22.0-snapshot-20261020204851"
50
+ "@medusajs/framework": "2.22.0"
47
51
  }
48
52
  }