api-ref: custom API reference (#4770)
* initialized next.js project * finished markdown sections * added operation schema component * change page metadata * eslint fixes * fixes related to deployment * added response schema * resolve max stack issue * support for different property types * added support for property types * added loading for components * added more loading * type fixes * added oneOf type * removed console * fix replace with push * refactored everything * use static content for description * fixes and improvements * added code examples section * fix path name * optimizations * fixed tag navigation * add support for admin and store references * general enhancements * optimizations and fixes * fixes and enhancements * added search bar * loading enhancements * added loading * added code blocks * added margin top * add empty response text * fixed oneOf parameters * added path and query parameters * general fixes * added base path env variable * small fix for arrays * enhancements * design enhancements * general enhancements * fix isRequired * added enum values * enhancements * general fixes * general fixes * changed oas generation script * additions to the introduction section * added copy button for code + other enhancements * fix response code block * fix metadata * formatted store introduction * move sidebar logic to Tags component * added test env variables * fix code block bug * added loading animation * added expand param + loading * enhance operation loading * made responsive + improvements * added loading provider * fixed loading * adjustments for small devices * added sidebar label for endpoints * added feedback component * fixed analytics * general fixes * listen to scroll for other headings * added sample env file * update api ref files + support new fields * fix for external docs link * added new sections * fix last item in sidebar not showing * move docs content to www/docs * change redirect url * revert change * resolve build errors * configure rewrites * changed to environment variable url * revert changing environment variable name * add environment variable for API path * fix links * fix tailwind settings * remove vercel file * reconfigured api route * move api page under api * fix page metadata * fix external link in navigation bar * update api spec * updated api specs * fixed google lint error * add max-height on request samples * add padding before loading * fix for one of name * fix undefined types * general fixes * remove response schema example * redesigned navigation bar * redesigned sidebar * fixed up paddings * added feedback component + report issue * fixed up typography, padding, and general styling * redesigned code blocks * optimization * added error timeout * fixes * added indexing with algolia + fixes * fix errors with algolia script * redesign operation sections * fix heading scroll * design fixes * fix padding * fix padding + scroll issues * fix scroll issues * improve scroll performance * fixes for safari * optimization and fixes * fixes to docs + details animation * padding fixes for code block * added tab animation * fixed incorrect link * added selection styling * fix lint errors * redesigned details component * added detailed feedback form * api reference fixes * fix tabs * upgrade + fixes * updated documentation links * optimizations to sidebar items * fix spacing in sidebar item * optimizations and fixes * fix endpoint path styling * remove margin * final fixes * change margin on small devices * generated OAS * fixes for mobile * added feedback modal * optimize dark mode button * fixed color mode useeffect * minimize dom size * use new style system * radius and spacing design system * design fixes * fix eslint errors * added meta files * change cron schedule * fix docusaurus configurations * added operating system to feedback data * change content directory name * fixes to contribution guidelines * revert renaming content * added api-reference to documentation workflow * fixes for search * added dark mode + fixes * oas fixes * handle bugs * added code examples for clients * changed tooltip text * change authentication to card * change page title based on selected section * redesigned mobile navbar * fix icon colors * fix key colors * fix medusa-js installation command * change external regex in algolia * change changeset * fix padding on mobile * fix hydration error * update depedencies
This commit is contained in:
Shahed Nasser
GitHub
@@ -0,0 +1,455 @@
|
||||
---
|
||||
description: 'Learn how to manage invites using the admin API. This includes listing, creating, accepting, resending, and deleting invites.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Manage Invites
|
||||
|
||||
In this document, you’ll learn how to manage invites using the admin API.
|
||||
|
||||
## Overview
|
||||
|
||||
You can use the invites admin API to manage and perform functionalities related to invites.
|
||||
|
||||
### Scenario
|
||||
|
||||
You want to add or use the following admin functionalities:
|
||||
|
||||
- List invites
|
||||
- Create an invite
|
||||
- Accept an invite
|
||||
- Resend an invite
|
||||
- Delete an invite
|
||||
|
||||
---
|
||||
|
||||
## 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](../../../development/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
|
||||
|
||||
Except for the Accept Invite endpoint, 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 Invites
|
||||
|
||||
You can list invites by sending a request to the [List Invite endpoint](https://docs.medusajs.com/api/admin#invites_getinvites):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.invites.list()
|
||||
.then(({ invites }) => {
|
||||
console.log(invites.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminInvites } from "medusa-react"
|
||||
|
||||
const Invites = () => {
|
||||
const { invites, isLoading } = useAdminInvites()
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{invites && !invites.length && <span>No Invites</span>}
|
||||
{invites && invites.length > 0 && (
|
||||
<ul>
|
||||
{invites.map((invite) => (
|
||||
<li key={invite.id}>{invite.user_email}</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default Invites
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/invites`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ invites }) => {
|
||||
console.log(invites.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X GET '<BACKEND_URL>/admin/invites' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint does not accept any parameters.
|
||||
|
||||
The request returns an array of invite endpoints.
|
||||
|
||||
---
|
||||
|
||||
## Create Invite
|
||||
|
||||
You can create an invite by sending a request to the [Create Invite endpoint](https://docs.medusajs.com/api/admin#invites_postinvites):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.invites.create({
|
||||
user: "user@example.com",
|
||||
role: "admin",
|
||||
})
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminCreateInvite } from "medusa-react"
|
||||
|
||||
const CreateInvite = () => {
|
||||
const createInvite = useAdminCreateInvite()
|
||||
// ...
|
||||
|
||||
const handleCreate = () => {
|
||||
createInvite.mutate({
|
||||
user: "user@example.com",
|
||||
role: "admin",
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default CreateInvite
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/invites`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
user: "user@example.com",
|
||||
role: "admin",
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/invites' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"user": "user@example.com",
|
||||
"role": "admin"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the following body parameters:
|
||||
|
||||
- `user`: a string indicating the email of the user.
|
||||
- `role`: a string indicating the role of the user. Its values can be `admin`, `member`, and `developer`.
|
||||
|
||||
The request does not return any data. If the invite was created successfully, the status code of the response will be `200`.
|
||||
|
||||
---
|
||||
|
||||
## Accept an Invite
|
||||
|
||||
A logged-out user can accept an invite, which would create a user for that user.
|
||||
|
||||
You can accept an invite by sending a request to the [Accept Invite endpoint](https://docs.medusajs.com/api/admin#invites_postinvitesinviteaccept):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.invites.accept({
|
||||
token,
|
||||
user: {
|
||||
first_name: "Brigitte",
|
||||
last_name: "Collier",
|
||||
password: "supersecret",
|
||||
},
|
||||
})
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminAcceptInvite } from "medusa-react"
|
||||
|
||||
const AcceptInvite = () => {
|
||||
const acceptInvite = useAdminAcceptInvite()
|
||||
// ...
|
||||
|
||||
const handleAccept = () => {
|
||||
acceptInvite.mutate({
|
||||
token,
|
||||
user: {
|
||||
first_name: "Brigitte",
|
||||
last_name: "Collier",
|
||||
password: "supersecret",
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default AcceptInvite
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/invites/accept`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
token,
|
||||
user: {
|
||||
first_name: "Brigitte",
|
||||
last_name: "Collier",
|
||||
password: "supersecret",
|
||||
},
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/invites/accept' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"token": "<TOKEN>",
|
||||
"user": {
|
||||
"first_name": "Brigitte",
|
||||
"last_name": "Collier",
|
||||
"password": "supersecret"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the following request body parameters:
|
||||
|
||||
- `token`: a string indicating the invitation’s token.
|
||||
- `user`: an object that has the following properties:
|
||||
- `first_name`: a string indicating the first name of the user.
|
||||
- `last_name`: a string indicating the last name of the user.
|
||||
- `password`: a string indicating the user’s password.
|
||||
|
||||
The request does not return any data. If the invite was accepted successfully, the status code of the response will be `200`.
|
||||
|
||||
---
|
||||
|
||||
## Resend an Invite
|
||||
|
||||
You can resend an invite if it’s not accepted yet. To resend an invite, send a request to the [Resend Invite endpoint](https://docs.medusajs.com/api/admin#invites_postinvitesinviteresend):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.invites.resend(inviteId)
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminResendInvite } from "medusa-react"
|
||||
|
||||
const ResendInvite = () => {
|
||||
const resendInvite = useAdminResendInvite(inviteId)
|
||||
// ...
|
||||
|
||||
const handleResend = () => {
|
||||
resendInvite.mutate()
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default ResendInvite
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/invites/${inviteId}/resend`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/invites/<INVITE_ID>/resend' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the invite ID as a path parameter.
|
||||
|
||||
The request does not return any data. If the invite was resent successfully, the status code of the response will be `200`.
|
||||
|
||||
---
|
||||
|
||||
## Delete an Invite
|
||||
|
||||
You can delete an invite by sending a request to the [Delete Invite endpoint](https://docs.medusajs.com/api/admin#invites_deleteinvitesinvite):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.invites.delete(inviteId)
|
||||
.then(({ id, object, deleted }) => {
|
||||
console.log(id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminDeleteInvite } from "medusa-react"
|
||||
|
||||
const DeleteInvite = () => {
|
||||
const deleteInvite = useAdminDeleteInvite(inviteId)
|
||||
// ...
|
||||
|
||||
const handleDelete = () => {
|
||||
deleteInvite.mutate()
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default DeleteInvite
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/invites/${inviteId}`, {
|
||||
credentials: "include",
|
||||
method: "DELETE",
|
||||
})
|
||||
.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/invites/<INVITE_ID>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the invite ID as a path parameter.
|
||||
|
||||
It deletes the invite and returns the following fields:
|
||||
|
||||
- `id`: The ID of the deleted invite.
|
||||
- `object`: The type of object that was deleted. In this case, the value will be `invite`.
|
||||
- `deleted`: A boolean value indicating whether the invite was deleted.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [How to implement user profiles](./manage-profile.mdx)
|
||||
- [How to manage users](./manage-users.mdx)
|
||||
@@ -0,0 +1,528 @@
|
||||
---
|
||||
description: 'Learn how to implement user profile management features using the admin APIs. This includes user authentication, updating the profile, and resetting the password.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Implement User Profiles
|
||||
|
||||
In this document, you’ll learn how to implement user profile management features using the admin APIs.
|
||||
|
||||
## Overview
|
||||
|
||||
The user’s admin APIs allow you to retrieve and perform admin functionalities on users.
|
||||
|
||||
### Scenario
|
||||
|
||||
You want to add or use the following admin functionalities:
|
||||
|
||||
- User authentication, meaning user log in and log out.
|
||||
- Manage profile, including retrieving profile details and updating profile.
|
||||
- Reset password
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../../development/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, JavaScript’s Fetch API, or cURL.
|
||||
|
||||
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
|
||||
|
||||
Aside from the User Login and Reset Password steps, other endpoints require you to be an authenticated admin user.
|
||||
|
||||
You can learn more about [authenticating as an admin user in the API reference](https://docs.medusajs.com/api/admin#authentication).
|
||||
|
||||
---
|
||||
|
||||
## User Authentication
|
||||
|
||||
### User Login
|
||||
|
||||
You can log in a user by sending a request to the [User Login endpoint](https://docs.medusajs.com/api/admin#auth_postauth):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.auth.createSession({
|
||||
email: "user@example.com",
|
||||
password: "supersecret",
|
||||
})
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminLogin } from "medusa-react"
|
||||
|
||||
const Login = () => {
|
||||
const adminLogin = useAdminLogin()
|
||||
// ...
|
||||
|
||||
const handleLogin = () => {
|
||||
adminLogin.mutate({
|
||||
email: "user@example.com",
|
||||
password: "supersecret",
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default Login
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/auth`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email: "user@example.com",
|
||||
password: "supersecret",
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/auth' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"email": "user@example.com",
|
||||
"password": "supersecret"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the following request body parameters:
|
||||
|
||||
- `email`: a string indicating the user’s email.
|
||||
- `password`: a string indicating the user’s password.
|
||||
|
||||
The request returns the logged-in user as an object.
|
||||
|
||||
### User Logout
|
||||
|
||||
You can log out a user by sending a request to the [User Logout endpoint](https://docs.medusajs.com/api/admin#auth_deleteauth):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.auth.deleteSession()
|
||||
.then(() => {
|
||||
// logged out successfully
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminDeleteSession } from "medusa-react"
|
||||
|
||||
const Logout = () => {
|
||||
const adminLogout = useAdminDeleteSession()
|
||||
// ...
|
||||
|
||||
const handleLogout = () => {
|
||||
adminLogout.mutate()
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default Logout
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/auth`, {
|
||||
credentials: "include",
|
||||
method: "DELETE",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(() => {
|
||||
// logged out successfully
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X DELETE '<BACKEND_URL>/admin/auth' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
The endpoint does not require any path or query parameters.
|
||||
|
||||
The request does not return any data. The response code will be `200` for successful log out.
|
||||
|
||||
---
|
||||
|
||||
## Retrieve User Profile Details
|
||||
|
||||
You can retrieve the current user’s details for their profile by sending a request to the [Get Current User endpoint](https://docs.medusajs.com/api/admin#auth_getauth):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.auth.getSession()
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminGetSession } from "medusa-react"
|
||||
|
||||
const Profile = () => {
|
||||
const { user, isLoading } = useAdminGetSession()
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{user && <span>{user.email}</span>}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default Profile
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/auth`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X GET '<BACKEND_URL>/admin/auth' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint does not require any parameters.
|
||||
|
||||
The request returns the current user as an object.
|
||||
|
||||
---
|
||||
|
||||
## Update User’s Profile Details
|
||||
|
||||
You can update a user’s details in their profile by sending a request to the [Update User endpoint](https://docs.medusajs.com/api/admin#users_postusersuser):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.users.update(userId, {
|
||||
first_name: "Marcellus",
|
||||
})
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import {
|
||||
useAdminDeleteSession,
|
||||
useAdminUpdateUser,
|
||||
} from "medusa-react"
|
||||
|
||||
const Profile = () => {
|
||||
const updateUser = useAdminUpdateUser(userId)
|
||||
// ...
|
||||
|
||||
const handleUpdate = () => {
|
||||
updateUser.mutate({
|
||||
first_name: "Marcellus",
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default Profile
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/users/${userId}`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
first_name: "Marcellus",
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/users/<USER_ID>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"first_name": "Marcellus"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the ID of the user as a path parameter.
|
||||
|
||||
In the request body, you can pass any of the user’s fields that you want to update as a parameter. In the example above, you pass the `first_name` parameter to update the user’s first name. You can refer to the [API reference](https://docs.medusajs.com/api/admin#users_postusersuser) to learn about other available parameters.
|
||||
|
||||
The request returns the updated user as an object.
|
||||
|
||||
---
|
||||
|
||||
## Reset Password
|
||||
|
||||
This section explains how you can reset the password of a user if they forgot their password.
|
||||
|
||||
### Step 1: Request Password Reset
|
||||
|
||||
The first step is to request a password reset. This would create in the Medusa backend a reset password token, which you typically would use in an email sent to the user. The email would include a link that allows the user to enter a new password, and the link would accept a token query parameter to be used in step 2.
|
||||
|
||||
:::note
|
||||
|
||||
Sending the password reset email is not handled by default in the Medusa backend. You can either use the SendGrid plugin which handles it, or manually subscribe to the `user.password_reset` event and send the email.
|
||||
|
||||
:::
|
||||
|
||||
You can request a password reset by sending a request to the [Request Password Reset endpoint](https://docs.medusajs.com/api/admin#users_postusersuserpasswordtoken):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.users.sendResetPasswordToken({
|
||||
email: "user@example.com",
|
||||
})
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminSendResetPasswordToken } from "medusa-react"
|
||||
|
||||
const Login = () => {
|
||||
const requestPasswordReset = useAdminSendResetPasswordToken()
|
||||
// ...
|
||||
|
||||
const handleResetPassword = () => {
|
||||
requestPasswordReset.mutate({
|
||||
email: "user@example.com",
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default Login
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/users/password-token`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email: "user@example.com",
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/users/password-token' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"email": "user@example.com"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the `email` parameter in the request body, which is the email of the user requesting to reset their password.
|
||||
|
||||
The request does not return any data. The response code will be `204` if the request was processed successfully.
|
||||
|
||||
### Step 2: Reset Password
|
||||
|
||||
After the user resets their password and, typically, receives an email with a link to reset their password, they should enter their new password. The new password, along with the token passed to this page are used to reset the password on the Medusa backend.
|
||||
|
||||
You can reset the password by sending a request to the [Reset Password endpoint](https://docs.medusajs.com/api/admin#users_postusersuserpassword):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.users.resetPassword({
|
||||
token: "supersecrettoken",
|
||||
password: "supersecret",
|
||||
})
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminResetPassword } from "medusa-react"
|
||||
|
||||
const ResetPassword = () => {
|
||||
const resetPassword = useAdminResetPassword()
|
||||
// ...
|
||||
|
||||
const handleResetPassword = () => {
|
||||
resetPassword.mutate({
|
||||
token: "supersecrettoken",
|
||||
password: "supersecret",
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default ResetPassword
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/users/reset-password`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
token: "supersecrettoken",
|
||||
password: "supersecret",
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/users/reset-password' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"token": "supersecrettoken",
|
||||
"password": "supersecret"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the following request body parameters:
|
||||
|
||||
- `token`: a string indicating the password reset token.
|
||||
- `password`: a string indicating the new password for the user.
|
||||
|
||||
You can also optionally pass the `email` parameter in the request body.
|
||||
|
||||
The request returns the user as an object, and the user is automatically logged in.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [How to manage users](./manage-users.mdx)
|
||||
@@ -0,0 +1,365 @@
|
||||
---
|
||||
description: 'Learn how to manage users using the admin APIs. This includes listing, creating, updating, and deleting users.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Manage Users
|
||||
|
||||
In this document, you’ll learn how to manage users using the admin APIs.
|
||||
|
||||
## Overview
|
||||
|
||||
You can use the user admin API to manage users and teams in the store.
|
||||
|
||||
### Scenario
|
||||
|
||||
You want to add or use the following admin functionalities:
|
||||
|
||||
- List users
|
||||
- Create a user
|
||||
- Update a user
|
||||
- Delete a user
|
||||
|
||||
---
|
||||
|
||||
## 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](../../../development/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 Users
|
||||
|
||||
You can retrieve users in a store by sending a request to the [List Users endpoint](https://docs.medusajs.com/api/admin#users_getusers):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.users.list()
|
||||
.then(({ users }) => {
|
||||
console.log(users.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminUsers } from "medusa-react"
|
||||
|
||||
const Users = () => {
|
||||
const { users, isLoading } = useAdminUsers()
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{users && !users.length && <span>No Users</span>}
|
||||
{users && users.length > 0 && (
|
||||
<ul>
|
||||
{users.map((user) => (
|
||||
<li key={user.id}>{user.email}</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default Users
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/users`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ users }) => {
|
||||
console.log(users.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X GET '<BACKEND_URL>/admin/users' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint does not require any parameters.
|
||||
|
||||
The request returns an array of user objects.
|
||||
|
||||
---
|
||||
|
||||
## Create a User
|
||||
|
||||
You can create a user by sending a request to the [Create User endpoint](https://docs.medusajs.com/api/admin#users_postusers):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.users.create({
|
||||
email: "user@example.com",
|
||||
password: "supersecret",
|
||||
})
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminCreateUser } from "medusa-react"
|
||||
|
||||
const CreateUser = () => {
|
||||
const createUser = useAdminCreateUser()
|
||||
// ...
|
||||
|
||||
const handleCreateUser = () => {
|
||||
createUser.mutate({
|
||||
email: "user@example.com",
|
||||
password: "supersecret",
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default CreateUser
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/users`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email: "user@example.com",
|
||||
password: "supersecret",
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/users' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"email": "user@example.com",
|
||||
"password": "supersecret"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the following request body parameters:
|
||||
|
||||
- `email`: a string indicating the email of the user.
|
||||
- `password`: a string indicating the password of the user.
|
||||
|
||||
The endpoint accepts other optional body parameters, such as first name or last name. Check the [API reference](https://docs.medusajs.com/api/admin#users_postusers) for details on optional body parameters.
|
||||
|
||||
The request returns the created user as an object.
|
||||
|
||||
---
|
||||
|
||||
## Update User
|
||||
|
||||
You can update a user’s details by sending a request to the [Update User endpoint](https://docs.medusajs.com/api/admin#users_postusersuser):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.users.update(userId, {
|
||||
first_name: "Marcellus",
|
||||
})
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminUpdateUser } from "medusa-react"
|
||||
|
||||
const UpdateUser = () => {
|
||||
const updateUser = useAdminUpdateUser(userId)
|
||||
// ...
|
||||
|
||||
const handleUpdateUser = () => {
|
||||
updateUser.mutate({
|
||||
first_name: "Marcellus",
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default UpdateUser
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/users/${userId}`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
first_name: "Marcellus",
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ user }) => {
|
||||
console.log(user.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="curl" label="cURL">
|
||||
|
||||
```bash
|
||||
curl -L -X POST '<BACKEND_URL>/admin/users/<USER_ID>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"first_name": "Marcellus"
|
||||
}'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the ID of the user as a path parameter.
|
||||
|
||||
In the request body, you can pass any of the user’s fields that you want to update as parameters. In the example above, you update the user’s `first_name`. Check the [API reference](https://docs.medusajs.com/api/admin#users_postusersuser) for all the optional parameters.
|
||||
|
||||
The request returns the updated user as an object.
|
||||
|
||||
---
|
||||
|
||||
## Delete a User
|
||||
|
||||
You can delete a user by sending a request to the [Delete User endpoint](https://docs.medusajs.com/api/admin#users_deleteusersuser):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.admin.users.delete(userId)
|
||||
.then(({ id, object, deleted }) => {
|
||||
console.log(id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAdminDeleteUser } from "medusa-react"
|
||||
|
||||
const DeleteUser = () => {
|
||||
const deleteUser = useAdminDeleteUser(userId)
|
||||
// ...
|
||||
|
||||
const handleDeleteUser = () => {
|
||||
deleteUser.mutate()
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default DeleteUser
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/admin/users/${userId}`, {
|
||||
credentials: "include",
|
||||
method: "DELETE",
|
||||
})
|
||||
.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/users/<USER_ID>' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the user ID as a path parameter.
|
||||
|
||||
It deletes the user and returns the following fields:
|
||||
|
||||
- `id`: The ID of the deleted user.
|
||||
- `object`: The type of object that was deleted. In this case, the value will be `user`.
|
||||
- `deleted`: A boolean value indicating whether the user was deleted.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [How to manage a user’s profile](./manage-profile.mdx)
|
||||
Reference in New Issue
Block a user