Skip to content

Commit

Permalink
docs: added manage users documentation (medusajs#4000)
Browse files Browse the repository at this point in the history 
* docs: added manage users documentation

* fix link
  • Loading branch information
@shahednasser
shahednasser authored May 3, 2023
1 parent b8e976e commit f9886a5
Show file tree
Hide file tree
Showing 4 changed files with 374 additions and 7 deletions.
6 changes: 6 additions & 0 deletions docs/content/modules/users/admin/manage-profile.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -520,3 +520,9 @@ This endpoint requires the following request body parameters:
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)
365 changes: 365 additions & 0 deletions docs/content/modules/users/admin/manage-users.mdx
View file
Original file line number Diff line number Diff line change
@@ -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.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#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](/api/admin/#section/Authentication).

---

## List Users

You can retrieve users in a store by sending a request to the [List Users endpoint](/api/admin#tag/Users/operation/GetUsers):

<Tabs groupId="request-type" wrapperClassName="code-tabs">
<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](/api/admin#tag/Users/operation/PostUsers):

<Tabs groupId="request-type" wrapperClassName="code-tabs">
<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](/api/admin#tag/Users/operation/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](/api/admin#tag/Users/operation/PostUsersUser):

<Tabs groupId="request-type" wrapperClassName="code-tabs">
<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](/api/admin#tag/Users/operation/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](/api/admin#tag/Users/operation/DeleteUsersUser):

<Tabs groupId="request-type" wrapperClassName="code-tabs">
<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.

This request 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)
3 changes: 1 addition & 2 deletions docs/content/modules/users/overview.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,11 @@ Admins can also manage their profile details.
<DocCardList colSize={6} items={[
{
type: 'link',
href: '#',
href: '/modules/users/admin/manage-users',
label: 'Admin: Manage Users',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to manage users using Admin APIs.',
isSoon: true
}
},
{
Expand Down
Loading

0 comments on commit f9886a5

Please sign in to comment.