> ## Documentation Index
> Fetch the complete documentation index at: https://docs.projexdesk.com/llms.txt
> Use this file to discover all available pages before exploring further.
# mFoundry Users API: List, Invite, and Manage Members
> Manage organization members via the mFoundry REST API. List users, retrieve profiles, invite new members, and update roles programmatically.
The Users API lets you manage every member of your mFoundry organization without leaving your own tooling. You can list current members, fetch individual profiles, programmatically invite new colleagues via email, and update roles as responsibilities change. All user endpoints sit under `/v1/users` and operate within the scope of the authenticated key's organization.
***
## GET /v1/users
List all users who are members of your organization, including users in the `invited` state who have not yet accepted their invitation. Results are paginated in reverse-chronological order.
Number of users to return per page. Defaults to `20`. Maximum is `100`.
Pagination cursor returned as `next_cursor` in a previous response. Omit to start from the first page.
**Example response:**
```json theme={null}
{
"data": [
{
"id": "user_abc123",
"email": "jane@example.com",
"name": "Jane Smith",
"role": "admin",
"created_at": "2024-02-01T10:00:00Z"
},
{
"id": "user_def456",
"email": "bob@example.com",
"name": "Bob Lee",
"role": "member",
"created_at": "2024-03-15T08:30:00Z"
}
],
"next_cursor": "cursor_abc999"
}
```
```bash cURL theme={null}
curl --request GET \
--url "https://api.mfoundry.io/v1/users?limit=20" \
--header "Authorization: Bearer YOUR_API_KEY"
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.mfoundry.io/v1/users?limit=20", {
headers: { "Authorization": "Bearer YOUR_API_KEY" },
});
const { data, next_cursor } = await response.json();
```
***
## GET /v1/users/:id
Retrieve a single user's full profile by their unique ID. This returns all fields including their role and the timestamp they joined (or were invited to) the organization.
The unique identifier of the user to retrieve (for example, `user_abc123`).
**Example response:**
```json theme={null}
{
"id": "user_abc123",
"email": "jane@example.com",
"name": "Jane Smith",
"role": "admin",
"status": "active",
"created_at": "2024-02-01T10:00:00Z",
"updated_at": "2024-05-10T14:22:00Z"
}
```
```bash cURL theme={null}
curl --request GET \
--url https://api.mfoundry.io/v1/users/user_abc123 \
--header "Authorization: Bearer YOUR_API_KEY"
```
```javascript JavaScript theme={null}
const response = await fetch(
"https://api.mfoundry.io/v1/users/user_abc123",
{
headers: { "Authorization": "Bearer YOUR_API_KEY" },
}
);
const user = await response.json();
```
***
## POST /v1/users
Invite a new user to your organization by email. mFoundry sends an invitation email immediately upon success. The new user's record is created with `status: invited` and becomes `active` once they accept the invitation.
The email address of the person you are inviting. Must be a valid email format and not already associated with an active member of your organization.
The role to assign to the invited user. Must be one of:
* `owner` — full administrative control
* `admin` — can manage members and most resources
* `member` — can create and edit resources
* `viewer` — read-only access
```bash cURL theme={null}
curl --request POST \
--url https://api.mfoundry.io/v1/users \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"email": "newteammate@example.com",
"role": "member"
}'
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.mfoundry.io/v1/users", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
email: "newteammate@example.com",
role: "member",
}),
});
const newUser = await response.json();
```
**Example response (`201 Created`):**
```json theme={null}
{
"id": "user_ghi789",
"email": "newteammate@example.com",
"name": null,
"role": "member",
"status": "invited",
"created_at": "2024-06-11T09:15:00Z",
"updated_at": "2024-06-11T09:15:00Z"
}
```
An invitation email is sent automatically to the provided address as soon as the API responds with `201 Created`. You do not need to trigger a separate send step. The invitation link expires after **72 hours** — if the recipient misses it, delete the user record and invite them again to generate a fresh link.
***
## PUT /v1/users/:id
Update a user's role within your organization. This is the only field you can change via the API; name and email changes must be made by the user themselves from their account settings.
The unique identifier of the user whose role you want to update.
The new role to assign. Must be one of: `owner`, `admin`, `member`, `viewer`.
```bash cURL theme={null}
curl --request PUT \
--url https://api.mfoundry.io/v1/users/user_abc123 \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"role": "admin"
}'
```
```javascript JavaScript theme={null}
const response = await fetch(
"https://api.mfoundry.io/v1/users/user_abc123",
{
method: "PUT",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ role: "admin" }),
}
);
const updated = await response.json();
```
**Example response:**
```json theme={null}
{
"id": "user_abc123",
"email": "jane@example.com",
"name": "Jane Smith",
"role": "admin",
"status": "active",
"created_at": "2024-02-01T10:00:00Z",
"updated_at": "2024-06-11T10:00:00Z"
}
```