Publishable API Keys

Queries and Mutations listed here are used to send requests to the Admin Publishable API Key API Routes.

All hooks listed require user authentication.

Publishable API Keys can be used to scope Store API calls with an API key, determining what resources are retrieved when querying the API. For example, a publishable API key can be associated with one or more sales channels.

When it is passed in the header of a request to the List Product store API Route, the sales channels are inferred from the key and only products associated with those sales channels are retrieved.

Admins can manage publishable API keys and their associated resources. Currently, only Sales Channels are supported as a resource.

Related Guide: How to manage publishable API keys.

Mutations

useAdminCreatePublishableApiKey

This hook creates a publishable API key.

Example

import React from "react"
import { useAdminCreatePublishableApiKey } from "medusa-react"

const CreatePublishableApiKey = () => {
  const createKey = useAdminCreatePublishableApiKey()
  // ...

  const handleCreate = (title: string) => {
    createKey.mutate({
      title,
    }, {
      onSuccess: ({ publishable_api_key }) => {
        console.log(publishable_api_key.id)
      }
    })
  }

  // ...
}

export default CreatePublishableApiKey

Mutation Function Parameters

AdminPostPublishableApiKeysReqAdminPostPublishableApiKeysReqRequired

The details of the publishable API key to create.

Mutation Function Returned Data

AdminPublishableApiKeysResAdminPublishableApiKeysResRequired

The publishable API key's details.

useAdminUpdatePublishableApiKey

This hook updates a publishable API key's details.

Example

import React from "react"
import { useAdminUpdatePublishableApiKey } from "medusa-react"

type Props = {
  publishableApiKeyId: string
}

const PublishableApiKey = ({
  publishableApiKeyId
}: Props) => {
  const updateKey = useAdminUpdatePublishableApiKey(
    publishableApiKeyId
  )
  // ...

  const handleUpdate = (title: string) => {
    updateKey.mutate({
      title,
    }, {
      onSuccess: ({ publishable_api_key }) => {
        console.log(publishable_api_key.id)
      }
    })
  }

  // ...
}

export default PublishableApiKey

Hook Parameters

idstringRequired

The publishable API key's ID.

Mutation Function Parameters

AdminPostPublishableApiKeysPublishableApiKeyReqAdminPostPublishableApiKeysPublishableApiKeyReqRequired

The details to update of the publishable API key.

Mutation Function Returned Data

AdminPublishableApiKeysResAdminPublishableApiKeysResRequired

The publishable API key's details.

useAdminDeletePublishableApiKey

This hook deletes a publishable API key. Associated resources, such as sales channels, are not deleted.

Example

import React from "react"
import { useAdminDeletePublishableApiKey } from "medusa-react"

type Props = {
  publishableApiKeyId: string
}

const PublishableApiKey = ({
  publishableApiKeyId
}: Props) => {
  const deleteKey = useAdminDeletePublishableApiKey(
    publishableApiKeyId
  )
  // ...

  const handleDelete = () => {
    deleteKey.mutate(void 0, {
      onSuccess: ({ id, object, deleted }) => {
        console.log(id)
      }
    })
  }

  // ...
}

export default PublishableApiKey

Hook Parameters

idstringRequired

The publishable API key's ID.

Mutation Function Returned Data

DeleteResponseDeleteResponseRequired

The response returned for a DELETE request.

useAdminRevokePublishableApiKey

This hook revokes a publishable API key. Revoking the publishable API Key can't be undone, and the key can't be used in future requests.

Example

import React from "react"
import { useAdminRevokePublishableApiKey } from "medusa-react"

type Props = {
  publishableApiKeyId: string
}

const PublishableApiKey = ({
  publishableApiKeyId
}: Props) => {
  const revokeKey = useAdminRevokePublishableApiKey(
    publishableApiKeyId
  )
  // ...

  const handleRevoke = () => {
    revokeKey.mutate(void 0, {
      onSuccess: ({ publishable_api_key }) => {
        console.log(publishable_api_key.revoked_at)
      }
    })
  }

  // ...
}

export default PublishableApiKey

Hook Parameters

idstringRequired

The publishable API key's ID.

Mutation Function Returned Data

AdminPublishableApiKeysResAdminPublishableApiKeysResRequired

The publishable API key's details.

useAdminAddPublishableKeySalesChannelsBatch

This hook adds a list of sales channels to a publishable API key.

Example

import React from "react"
import {
  useAdminAddPublishableKeySalesChannelsBatch,
} from "medusa-react"

type Props = {
  publishableApiKeyId: string
}

const PublishableApiKey = ({
  publishableApiKeyId
}: Props) => {
  const addSalesChannels = 
    useAdminAddPublishableKeySalesChannelsBatch(
      publishableApiKeyId
    )
  // ...

  const handleAdd = (salesChannelId: string) => {
    addSalesChannels.mutate({
      sales_channel_ids: [
        {
          id: salesChannelId,
        },
      ],
    }, {
      onSuccess: ({ publishable_api_key }) => {
        console.log(publishable_api_key.id)
      }
    })
  }

  // ...
}

export default PublishableApiKey

Hook Parameters

idstringRequired

The publishable API key's ID.

Mutation Function Parameters

AdminPostPublishableApiKeySalesChannelsBatchReqAdminPostPublishableApiKeySalesChannelsBatchReqRequired

The details of the sales channels to add to the publishable API key.

Mutation Function Returned Data

AdminPublishableApiKeysResAdminPublishableApiKeysResRequired

The publishable API key's details.

useAdminRemovePublishableKeySalesChannelsBatch

This hook removes a list of sales channels from a publishable API key. This doesn't delete the sales channels and only removes the association between them and the publishable API key.

Example

import React from "react"
import { 
  useAdminRemovePublishableKeySalesChannelsBatch,
} from "medusa-react"

type Props = {
  publishableApiKeyId: string
}

const PublishableApiKey = ({
  publishableApiKeyId
}: Props) => {
  const deleteSalesChannels = 
    useAdminRemovePublishableKeySalesChannelsBatch(
      publishableApiKeyId
    )
  // ...

  const handleDelete = (salesChannelId: string) => {
    deleteSalesChannels.mutate({
      sales_channel_ids: [
        {
          id: salesChannelId,
        },
      ],
    }, {
      onSuccess: ({ publishable_api_key }) => {
        console.log(publishable_api_key.id)
      }
    })
  }

  // ...
}

export default PublishableApiKey

Hook Parameters

idstringRequired

The publishable API key's ID.

Mutation Function Parameters

AdminDeletePublishableApiKeySalesChannelsBatchReqAdminDeletePublishableApiKeySalesChannelsBatchReqRequired

The details of the sales channels to remove from the publishable API key.

Mutation Function Returned Data

AdminPublishableApiKeysResAdminPublishableApiKeysResRequired

The publishable API key's details.

Queries

useAdminPublishableApiKey

This hook retrieves a publishable API key's details.

Example

import React from "react"
import { 
  useAdminPublishableApiKey,
} from "medusa-react"

type Props = {
  publishableApiKeyId: string
}

const PublishableApiKey = ({
  publishableApiKeyId
}: Props) => {
  const { publishable_api_key, isLoading } = 
    useAdminPublishableApiKey(
      publishableApiKeyId
    )
 
    
  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {publishable_api_key && <span>{publishable_api_key.title}</span>}
    </div>
  )
}

export default PublishableApiKey

Hook Parameters

idstringRequired

The publishable API key's ID.

Query Returned Data

publishable_api_keyPublishableApiKeyRequired

Publishable API key details.

useAdminPublishableApiKeys

This hook retrieves a list of publishable API keys. The publishable API keys can be filtered by fields such as q passed in query. The publishable API keys can also be paginated.

Example

To list publishable API keys:

import React from "react"
import { PublishableApiKey } from "@medusajs/medusa"
import { useAdminPublishableApiKeys } from "medusa-react"

const PublishableApiKeys = () => {
  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 PublishableApiKeys

By default, only the first 20 records are retrieved. You can control pagination by specifying the limit and offset properties:

import React from "react"
import { PublishableApiKey } from "@medusajs/medusa"
import { useAdminPublishableApiKeys } from "medusa-react"

const PublishableApiKeys = () => {
  const { 
    publishable_api_keys, 
    limit,
    offset,
    isLoading
  } = 
    useAdminPublishableApiKeys({
      limit: 50,
      offset: 0
    })

  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 PublishableApiKeys

Hook Parameters

queryGetPublishableApiKeysParams

Filters and pagination configurations to apply on the retrieved publishable API keys.

Query Returned Data

limitnumberRequired

The maximum number of items that can be returned in the list.

offsetnumberRequired

The number of items skipped before the returned items in the list.

countnumberRequired

The total number of items available.

publishable_api_keysPublishableApiKey[]Required

An array of publishable API keys details.

useAdminPublishableApiKeySalesChannels

This hook lists the sales channels associated with a publishable API key. The sales channels can be filtered by fields such as q passed in the query parameter.

Example

import React from "react"
import { 
  useAdminPublishableApiKeySalesChannels,
} from "medusa-react"

type Props = {
  publishableApiKeyId: string
}

const SalesChannels = ({
  publishableApiKeyId
}: Props) => {
  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) => (
            <li key={salesChannel.id}>{salesChannel.name}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default SalesChannels

Hook Parameters

idstringRequired

The publishable API Key's ID.

queryGetPublishableApiKeySalesChannelsParams

Filters to apply on the retrieved sales channels.

Query Returned Data

sales_channelsSalesChannel[]Required

An array of sales channels details.

Was this section helpful?

Mutations​

useAdminCreatePublishableApiKey​

Example​

Mutation Function Parameters​

Mutation Function Returned Data​

useAdminUpdatePublishableApiKey​

Example​

Hook Parameters​

Mutation Function Parameters​

Mutation Function Returned Data​

useAdminDeletePublishableApiKey​

Example​

Hook Parameters​

Mutation Function Returned Data​

useAdminRevokePublishableApiKey​

Example​

Hook Parameters​

Mutation Function Returned Data​

useAdminAddPublishableKeySalesChannelsBatch​

Example​

Hook Parameters​

Mutation Function Parameters​

Mutation Function Returned Data​

useAdminRemovePublishableKeySalesChannelsBatch​

Example​

Hook Parameters​

Mutation Function Parameters​

Mutation Function Returned Data​

Queries​

useAdminPublishableApiKey​

Example​

Hook Parameters​

Query Returned Data​

useAdminPublishableApiKeys​

Example​

Hook Parameters​

Query Returned Data​

useAdminPublishableApiKeySalesChannels​

Example​

Hook Parameters​

Query Returned Data​

Mutations

useAdminCreatePublishableApiKey

Example

Mutation Function Parameters

Mutation Function Returned Data

useAdminUpdatePublishableApiKey

Example

Hook Parameters

Mutation Function Parameters

Mutation Function Returned Data

useAdminDeletePublishableApiKey

Example

Hook Parameters

Mutation Function Returned Data

useAdminRevokePublishableApiKey

Example

Hook Parameters

Mutation Function Returned Data

useAdminAddPublishableKeySalesChannelsBatch

Example

Hook Parameters

Mutation Function Parameters

Mutation Function Returned Data

useAdminRemovePublishableKeySalesChannelsBatch

Example

Hook Parameters

Mutation Function Parameters

Mutation Function Returned Data

Queries

useAdminPublishableApiKey

Example

Hook Parameters

Query Returned Data

useAdminPublishableApiKeys

Example

Hook Parameters

Query Returned Data

useAdminPublishableApiKeySalesChannels

Example

Hook Parameters

Query Returned Data