mFoundry Users API: List, Invite, and Manage Members

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.

integer

Number of users to return per page. Defaults to 20. Maximum is 100.

string

Pagination cursor returned as next_cursor in a previous response. Omit to start from the first page.

Example response:

{
  "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"
}

curl --request GET \
  --url "https://api.mfoundry.io/v1/users?limit=20" \
  --header "Authorization: Bearer YOUR_API_KEY"

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.

string

required

The unique identifier of the user to retrieve (for example, user_abc123).

Example response:

{
  "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"
}

curl --request GET \
  --url https://api.mfoundry.io/v1/users/user_abc123 \
  --header "Authorization: Bearer YOUR_API_KEY"

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.

string

required

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.

string

required

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

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"
  }'

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):

{
  "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.

string

required

The unique identifier of the user whose role you want to update.

string

required

The new role to assign. Must be one of: owner, admin, member, viewer.

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"
  }'

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:

{
  "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"
}

Overview

Endpoints

mFoundry Users API: List, Invite, and Manage Members

GET /v1/users

GET /v1/users/:id

POST /v1/users

PUT /v1/users/:id

​GET /v1/users

​GET /v1/users/:id

​POST /v1/users

​PUT /v1/users/:id

GET /v1/users

GET /v1/users/:id

POST /v1/users

PUT /v1/users/:id