docs: added manage invites documentation (#4001)
* docs: added manage invites documentation * eslint fixes * fixed indentation
This commit is contained in:
Shahed Nasser
GitHub
455
docs/content/modules/users/admin/manage-invites.mdx
Normal file
455
docs/content/modules/users/admin/manage-invites.mdx
Normal file
@@ -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.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#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](/api/admin/#section/Authentication).
|
||||
|
||||
---
|
||||
|
||||
## List Invites
|
||||
|
||||
You can list invites by sending a request to the [List Invite endpoint](/api/admin#tag/Invites/operation/GetInvites):
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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](/api/admin#tag/Invites/operation/PostInvites):
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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](/api/admin#tag/Invites/operation/PostInvitesInviteAccept):
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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](/api/admin#tag/Invites/operation/PostInvitesInviteResend):
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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](/api/admin#tag/Invites/operation/DeleteInvitesInvite):
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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)
|
||||
@@ -6,7 +6,7 @@ addHowToData: true
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Manage a User’s Profile
|
||||
# How to Implement User Profiles
|
||||
|
||||
In this document, you’ll learn how to implement user profile management features using the admin APIs.
|
||||
|
||||
|
||||
@@ -352,7 +352,7 @@ curl -L -X DELETE '<BACKEND_URL>/admin/users/<USER_ID>' \
|
||||
|
||||
This endpoint requires the user ID as a path parameter.
|
||||
|
||||
This request requires the user ID as a path parameter. It deletes the user and returns the following fields:
|
||||
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`.
|
||||
|
||||
Reference in New Issue
Block a user