docs: create docs workspace (#5174)
* docs: migrate ui docs to docs universe * created yarn workspace * added eslint and tsconfig configurations * fix eslint configurations * fixed eslint configurations * shared tailwind configurations * added shared ui package * added more shared components * migrating more components * made details components shared * move InlineCode component * moved InputText * moved Loading component * Moved Modal component * moved Select components * Moved Tooltip component * moved Search components * moved ColorMode provider * Moved Notification components and providers * used icons package * use UI colors in api-reference * moved Navbar component * used Navbar and Search in UI docs * added Feedback to UI docs * general enhancements * fix color mode * added copy colors file from ui-preset * added features and enhancements to UI docs * move Sidebar component and provider * general fixes and preparations for deployment * update docusaurus version * adjusted versions * fix output directory * remove rootDirectory property * fix yarn.lock * moved code component * added vale for all docs MD and MDX * fix tests * fix vale error * fix deployment errors * change ignore commands * add output directory * fix docs test * general fixes * content fixes * fix announcement script * added changeset * fix vale checks * added nofilter option * fix vale error
This commit is contained in:
Shahed Nasser
GitHub
@@ -0,0 +1,771 @@
|
||||
---
|
||||
description: 'Learn how to implement publishable API key functionalities for admins in Medusa using the REST APIs. This includes how to list, create, update, and delete a publishable API key.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Manage Publishable API Keys
|
||||
|
||||
In this document, you’ll learn how to manage the publishable API keys using the admin APIs.
|
||||
|
||||
## Overview
|
||||
|
||||
Publishable API keys allow you to associate a set of resources with an API key. You can then pass that API key in storefront requests to guarantee that processed or returned data is within the scope you defined when creating the API key.
|
||||
|
||||
Currently, publishable API keys can only be associated with sales channels.
|
||||
|
||||
Using the Admin APIs, you can manage your Publishable API Keys.
|
||||
|
||||
:::note
|
||||
|
||||
Publishable API keys are only for client-side use. They can be publicly accessible in your code, as they are not authorized for the Admin API.
|
||||
|
||||
:::
|
||||
|
||||
### Scenario
|
||||
|
||||
You want to use or implement the following admin functionalities:
|
||||
|
||||
- Manage publishable keys including listing, creating, updating, and deleting them.
|
||||
- Manage sales channels associated with a publishable API key including listing, adding, and deleting them from the publishable API key.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Components
|
||||
|
||||
It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../backend/install.mdx) to get started.
|
||||
|
||||
### JS Client
|
||||
|
||||
This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.
|
||||
|
||||
If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration).
|
||||
|
||||
### Medusa React
|
||||
|
||||
This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.
|
||||
|
||||
If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#usage).
|
||||
|
||||
### Authenticated Admin User
|
||||
|
||||
You must be an authenticated admin user before following along with the steps in the tutorial.
|
||||
|
||||
You can learn more about [authenticating as an admin user in the API reference](https://docs.medusajs.com/api/admin#authentication).
|
||||
|
||||
---
|
||||
|
||||
## List Publishable API Keys
|
||||
|
||||
You can retrieve a list of publishable API keys by sending a request to the [List Publishable API Keys](https://docs.medusajs.com/api/admin#publishable-api-keys_getpublishableapikeys) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.publishableApiKeys.list()
|
||||
.then(({ publishable_api_keys, count, limit, offset }) => {
|
||||
console.log(publishable_api_keys)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { PublishableApiKey } from "@medusajs/medusa"
|
||||
import { useAdminPublishableApiKeys } from "medusa-react"
|
||||
|
||||
const PublishabelApiKeys = () => {
|
||||
const { publishable_api_keys, isLoading } =
|
||||
useAdminPublishableApiKeys()
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{publishable_api_keys && !publishable_api_keys.length && (
|
||||
<span>No Publishable API Keys</span>
|
||||
)}
|
||||
{publishable_api_keys &&
|
||||
publishable_api_keys.length > 0 && (
|
||||
<ul>
|
||||
{publishable_api_keys.map(
|
||||
(publishableApiKey: PublishableApiKey) => (
|
||||
<li key={publishableApiKey.id}>
|
||||
{publishableApiKey.title}
|
||||
</li>
|
||||
)
|
||||
)}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default PublishabelApiKeys
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/publishable-api-keys`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ publishable_api_keys, count, limit, offset }) => {
|
||||
console.log(publishable_api_keys)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X GET '<BACKEND_URL>/admin/publishable-api-keys' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request does not require any path parameters. You can pass it optional query parameters related to expanding fields and pagination, which you can check out in the [API reference](https://docs.medusajs.com/api/admin#publishable-api-keys_getpublishableapikeys).
|
||||
|
||||
This request returns the following data in the response:
|
||||
|
||||
- `publishable_api_keys`: An array of publishable API keys.
|
||||
- `limit`: The maximum number of keys that can be returned.
|
||||
- `offset`: The number of keys skipped in the result.
|
||||
- `count`: The total number of keys available.
|
||||
|
||||
:::note
|
||||
|
||||
You can learn more about pagination in the [API reference](https://docs.medusajs.com/api/admin#pagination).
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Create a Publishable API Key
|
||||
|
||||
You can create a publishable API key by sending a request to the [Create Publishable API Key](https://docs.medusajs.com/api/admin#publishable-api-keys_postpublishableapikeys) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.publishableApiKeys.create({
|
||||
title: "Web API Key",
|
||||
})
|
||||
.then(({ publishable_api_key }) => {
|
||||
console.log(publishable_api_key.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminCreatePublishableApiKey } from "medusa-react"
|
||||
|
||||
const CreatePublishableApiKey = () => {
|
||||
const createKey = useAdminCreatePublishableApiKey()
|
||||
// ...
|
||||
|
||||
const handleCreate = (title: string) => {
|
||||
createKey.mutate({
|
||||
title,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default CreatePublishableApiKey
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/publishable-api-keys`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
title: "Web API Key",
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ publishable_api_key }) => {
|
||||
console.log(publishable_api_key.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/publishable-api-keys' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"title": "Web API Key"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires a body parameter `title`, which is the title of the Publishable API Key.
|
||||
|
||||
It returns the created publishable API key in the response.
|
||||
|
||||
---
|
||||
|
||||
## Update a Publishable API Key
|
||||
|
||||
You can update a publishable API key’s details by sending a request to the [Update Publishable API Key](https://docs.medusajs.com/api/admin#publishable-api-keys_postpublishableapikyspublishableapikey) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.publishableApiKeys.update(publishableApiKeyId, {
|
||||
title: "Web API Key",
|
||||
})
|
||||
.then(({ publishable_api_key }) => {
|
||||
console.log(publishable_api_key.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminUpdatePublishableApiKey } from "medusa-react"
|
||||
|
||||
const UpdatePublishableApiKey = () => {
|
||||
const updateKey = useAdminUpdatePublishableApiKey(
|
||||
publishableApiKeyId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleUpdate = (title: string) => {
|
||||
updateKey.mutate({
|
||||
title,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default UpdatePublishableApiKey
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/publishable-api-keys/${publishableApiKeyId}`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
title: "Web API Key",
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ publishable_api_key }) => {
|
||||
console.log(publishable_api_key.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/publishable-api-keys/<PUBLISHABLE_API_KEY>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"title": "Web API Key"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the ID of the publishable API key as a path parameter. In its body, it optionally accepts the new `title` of the publishable API key.
|
||||
|
||||
This request returns the update publishable API key object in the response.
|
||||
|
||||
---
|
||||
|
||||
## Revoke a Publishable API Key
|
||||
|
||||
Revoking a publishable API key does not remove it, but does not allow using it in future requests.
|
||||
|
||||
You can revoke a publishable API key by sending a request to the [Revoke Publishable API Key](https://docs.medusajs.com/api/admin#publishable-api-keys_postpublishableapikeyspublishableapikeyrevoke) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.publishableApiKeys.revoke(publishableApiKeyId)
|
||||
.then(({ publishable_api_key }) => {
|
||||
console.log(publishable_api_key.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminRevokePublishableApiKey } from "medusa-react"
|
||||
|
||||
const PublishableApiKey = () => {
|
||||
const revokeKey = useAdminRevokePublishableApiKey(
|
||||
publishableApiKeyId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleRevoke = () => {
|
||||
revokeKey.mutate()
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default PublishableApiKey
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/admin/publishable-api-keys/${publishableApiKeyId}/revoke`,
|
||||
{
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ publishable_api_key }) => {
|
||||
console.log(publishable_api_key.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/publishable-api-keys/<PUBLISHABLE_API_KEY>/revoke' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the ID of the publishable API key as a path parameter. It returns the updated publishable API key in the response.
|
||||
|
||||
---
|
||||
|
||||
## Delete a Publishable API Key
|
||||
|
||||
You can delete a publishable API key by sending a request to the [Delete Publishable API Key](https://docs.medusajs.com/api/admin#publishable-api-keys_deletepublishableapikeyspublishableapikey) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.publishableApiKeys.delete(publishableApiKeyId)
|
||||
.then(({ id, object, deleted }) => {
|
||||
console.log(id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminDeletePublishableApiKey } from "medusa-react"
|
||||
|
||||
const PublishableApiKey = () => {
|
||||
const deleteKey = useAdminDeletePublishableApiKey(
|
||||
publishableApiKeyId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleDelete = () => {
|
||||
deleteKey.mutate()
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default PublishableApiKey
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/publishable-api-keys/${publishableApiKeyId}`, {
|
||||
method: "DELETE",
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ id, object, deleted }) => {
|
||||
console.log(id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X DELETE '<BACKEND_URL>/admin/publishable-api-keys/<PUBLISHABLE_API_KEY>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the ID of the publishable API key as a path parameter.
|
||||
|
||||
It returns the following data in the response:
|
||||
|
||||
- `id`: The ID of the deleted publishable API key.
|
||||
- `object`: A string indicating the type of object deleted. By default, its value is `publishable_api_key`.
|
||||
- `deleted`: A boolean value indicating whether the publishable API key was deleted or not.
|
||||
|
||||
---
|
||||
|
||||
## Manage Sales Channels of Publishable API Keys
|
||||
|
||||
This section covers how to manage sales channels in a publishable API key. This doesn’t affect sales channels and their data, only its association with the publishable API key.
|
||||
|
||||
### List Sales Channels of a Publishable API Key
|
||||
|
||||
You can retrieve the list of sales channels associated with a publishable API key by sending a request to the [List Sales Channels](https://docs.medusajs.com/api/admin#sales-channels_getsaleschannels) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.publishableApiKeys
|
||||
.listSalesChannels(publishableApiKeyId)
|
||||
.then(({ sales_channels }) => {
|
||||
console.log(sales_channels)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { SalesChannel } from "@medusajs/medusa"
|
||||
import {
|
||||
useAdminPublishableApiKeySalesChannels,
|
||||
} from "medusa-react"
|
||||
|
||||
const SalesChannels = () => {
|
||||
const { sales_channels, isLoading } =
|
||||
useAdminPublishableApiKeySalesChannels(
|
||||
publishableApiKeyId
|
||||
)
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{sales_channels && !sales_channels.length && (
|
||||
<span>No Sales Channels</span>
|
||||
)}
|
||||
{sales_channels && sales_channels.length > 0 && (
|
||||
<ul>
|
||||
{sales_channels.map((salesChannel: SalesChannel) => (
|
||||
<li key={salesChannel.id}>{salesChannel.name}</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default SalesChannels
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/admin/publishable-api-keys/${publishableApiKeyId}/sales-channels`,
|
||||
{
|
||||
credentials: "include",
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ sales_channels }) => {
|
||||
console.log(sales_channels)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X GET '<BACKEND_URL>/admin/publishable-api-keys/<PUBLISHABLE_API_KEY>/sales-channels' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the ID of the publishable API key as a path parameter.
|
||||
|
||||
It returns an array of sales channels associated with the publishable API key in the response.
|
||||
|
||||
### Add Sales Channels to Publishable API Key
|
||||
|
||||
You can add a sales channel to a publishable API key by sending a request to the [Add Sales Channels](https://docs.medusajs.com/api/admin#publishable-api-keys_postpublishableapikeysaleschannelschannelsbatch) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.publishableApiKeys.addSalesChannelsBatch(
|
||||
publishableApiKeyId,
|
||||
{
|
||||
sales_channel_ids: [
|
||||
{
|
||||
id: salesChannelId,
|
||||
},
|
||||
],
|
||||
}
|
||||
)
|
||||
.then(({ publishable_api_key }) => {
|
||||
console.log(publishable_api_key.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import {
|
||||
useAdminAddPublishableKeySalesChannelsBatch,
|
||||
} from "medusa-react"
|
||||
|
||||
const PublishableApiKey = () => {
|
||||
const addSalesChannels =
|
||||
useAdminAddPublishableKeySalesChannelsBatch(
|
||||
publishableApiKeyId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleAdd = (salesChannelId: string) => {
|
||||
addSalesChannels.mutate({
|
||||
sales_channel_ids: [
|
||||
{
|
||||
id: salesChannelId,
|
||||
},
|
||||
],
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default PublishableApiKey
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/admin/publishable-api-keys/${publishableApiKeyId}/sales-channels/batch`,
|
||||
{
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
sales_channel_ids: [
|
||||
{
|
||||
id: salesChannelId,
|
||||
},
|
||||
],
|
||||
}),
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ publishable_api_key }) => {
|
||||
console.log(publishable_api_key.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/publishable-api-keys/<PUBLISHABLE_API_KEY>/sales-channels/batch' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"sales_channel_ids": [
|
||||
{
|
||||
"id": "<SALES_CHANNEL_ID>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires passing the ID of the publishable API key as a path parameter.
|
||||
|
||||
In its body parameters, it’s required to pass the `sales_channel_ids` array parameter. Each item in the array is an object containing an `id` property, with its value being the ID of the sales channel to add to the publishable API key.
|
||||
|
||||
You can add more than one sales channel in the same request by passing each of them as an object in the array.
|
||||
|
||||
This request returns the updated publishable API key in the response.
|
||||
|
||||
### Delete Sales Channels from a Publishable API Key
|
||||
|
||||
You can delete a sales channel from a publishable API key by sending a request to the [Delete Sales Channels](https://docs.medusajs.com/api/admin#publishable-api-keys_deletepublishableapikeysaleschannelschannelsbatch) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.publishableApiKeys.deleteSalesChannelsBatch(
|
||||
publishableApiKeyId,
|
||||
{
|
||||
sales_channel_ids: [
|
||||
{
|
||||
id: salesChannelId,
|
||||
},
|
||||
],
|
||||
}
|
||||
)
|
||||
.then(({ publishable_api_key }) => {
|
||||
console.log(publishable_api_key.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import {
|
||||
useAdminRemovePublishableKeySalesChannelsBatch,
|
||||
} from "medusa-react"
|
||||
|
||||
const PublishableApiKey = () => {
|
||||
const deleteSalesChannels =
|
||||
useAdminRemovePublishableKeySalesChannelsBatch(
|
||||
publishableApiKeyId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleDelete = (salesChannelId: string) => {
|
||||
deleteSalesChannels.mutate({
|
||||
sales_channel_ids: [
|
||||
{
|
||||
id: salesChannelId,
|
||||
},
|
||||
],
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default PublishableApiKey
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/admin/publishable-api-keys/${publishableApiKeyId}/sales-channels/batch`,
|
||||
{
|
||||
method: "DELETE",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
sales_channel_ids: [
|
||||
{
|
||||
id: salesChannelId,
|
||||
},
|
||||
],
|
||||
}),
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ publishable_api_key }) => {
|
||||
console.log(publishable_api_key.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X DELETE '<BACKEND_URL>/admin/publishable-api-keys/<PUBLISHABLE_API_KEY>/sales-channels/batch' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"sales_channel_ids": [
|
||||
{
|
||||
"id": "<SALES_CHANNEL_ID>"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request requires the ID of the publishable API key as a path parameter.
|
||||
|
||||
In its body parameters, it’s required to pass the `sales_channel_ids` array parameter. Each item in the array is an object containing an `id` property, with its value being the ID of the sales channel to delete from the publishable API key.
|
||||
|
||||
You can delete more than one sales channel in the same request by passing each of them as an object in the array.
|
||||
|
||||
This request returns the updated publishable API key in the response.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Use publishable API keys in client requests](../storefront/use-in-requests.md)
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
description: 'Learn what publishable API keys are and how they can be used in the Medusa backend. Publishable API keys can be used to scope API calls with an API key.'
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import Icons from '@theme/Icon';
|
||||
|
||||
# Publishable API Keys
|
||||
|
||||
In this document, you’ll learn about Publishable API Keys and their architecture.
|
||||
|
||||
## Introduction
|
||||
|
||||
While using Medusa’s APIs, you might have to pass some query parameters for certain resources with every or most requests.
|
||||
|
||||
Taking Sales Channels as an example, you have to pass the Sales Channel’s ID as a query parameter to all the necessary endpoints, such as the List Products endpoint.
|
||||
|
||||
This is a tedious and error-prone process. This is where Publishable API Keys are useful.
|
||||
|
||||
Publishable API Keys can be used to scope API calls with an API key, determining what resources are retrieved when querying the API. Currently, they can be associated only with Sales Channels.
|
||||
|
||||
For example, you can associate an API key with a B2B channel, then, on the storefront, retrieve only products available in that channel using the API key.
|
||||
|
||||
---
|
||||
|
||||
## PublishableApiKey Entity Overview
|
||||
|
||||
The `PublishableApiKey` entity represents a publishable API key that is stored in the database. Some of its important attributes include:
|
||||
|
||||
- `id`: The ID of the publishable API key. This is the API key you’ll use in your API requests.
|
||||
- `created_by`: The ID of the user that created this API key.
|
||||
- `revoked_by`: The ID of the user that revoked this API key. A revoked publishable API key cannot be used in requests.
|
||||
|
||||
---
|
||||
|
||||
## Relation to Other Entities
|
||||
|
||||
### Sales Channels
|
||||
|
||||
A publishable API key can be associated with more than one sales channel, and a sales channel can be associated with more than one publishable API key.
|
||||
|
||||
The relation is represented by the entity `PublishableApiKeySalesChannel`.
|
||||
|
||||
---
|
||||
|
||||
## Custom Development
|
||||
|
||||
Developers can manage Publishable API Keys and use them when making requests to the Store APIs.
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/publishable-api-keys/admin/manage-publishable-api-keys',
|
||||
label: 'Admin: Manage Publishable API Keys',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to manage publishable API keys using Admin APIs.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/development/publishable-api-keys/storefront/use-in-requests',
|
||||
label: 'Storefront: Use in Requests',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to use publishable API keys in a storefront.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
description: 'Learn how to use Publishable API Keys in Client Requests using Medusa JS Client, Medusa React, or other methods.'
|
||||
---
|
||||
|
||||
# Use Publishable API Keys in Client Requests
|
||||
|
||||
In this document, you'll learn how to use Publishable API Keys in client requests.
|
||||
|
||||
:::note
|
||||
|
||||
[Publishable API keys](../index.mdx) are only for client-side use. They can be publicly accessible in your code, as they are not authorized for the Admin API.
|
||||
|
||||
:::
|
||||
|
||||
## Default Behaviour In Product Store Endpoints
|
||||
|
||||
If you don't pass a publishable API Key for the store endpoints `/store/products` and `/store/products/{product_id}`, the default sales channel of the store is assigned to the request.
|
||||
|
||||
---
|
||||
|
||||
## Using Medusa JS Client
|
||||
|
||||
When using [Medusa’s JS Client](../../../js-client/overview.md), you can pass it to the client only once when you create the instance of the client:
|
||||
|
||||
```ts
|
||||
const medusa = new Medusa({
|
||||
maxRetries: 3,
|
||||
baseUrl: "https://api.example.com",
|
||||
publishableApiKey,
|
||||
})
|
||||
```
|
||||
|
||||
This will add the API key as in the header parameter `x-publishable-api-key` on all requests.
|
||||
|
||||
You can also use the `setPublishableKey` method to set it at a later point:
|
||||
|
||||
```ts
|
||||
const medusa = new Medusa({
|
||||
// ...
|
||||
})
|
||||
|
||||
// at a later point
|
||||
medusa.setPublishableKey(publishableApiKey)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using Medusa React
|
||||
|
||||
You can pass the publishable API key to the `MedusaProvider` component:
|
||||
|
||||
```tsx
|
||||
const App = () => {
|
||||
return (
|
||||
<MedusaProvider
|
||||
queryClientProviderProps={{ client: queryClient }}
|
||||
baseUrl="http://localhost:9000"
|
||||
// ...
|
||||
publishableApiKey={publishableApiKey}
|
||||
>
|
||||
<MyStorefront />
|
||||
</MedusaProvider>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Then, the API key will be passed in the header parameter `x-publishable-api-key` of every request.
|
||||
|
||||
---
|
||||
|
||||
## Using Other Methods
|
||||
|
||||
For other ways of sending requests to your Medusa backend, such as using the Fetch API, you must pass `x-publishable-api-key` in the header of every request. Its value is the publishable API key’s `id`.
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/products`, {
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"x-publishable-api-key": publishableApiKey,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Manage publishable keys as an admin](../admin/manage-publishable-api-keys.mdx)
|
||||
Reference in New Issue
Block a user