Add a User

11 min

API Endpoint Documentation: /api/users/add

Description:

This endpoint allows you to add one or more users to the system by sending a POST request. The request body contains user details such as name, email, password, and associated groups.

Endpoint:

POST https://admin.<your-site>.com/api/users/add

Headers:

accept: application/json Specifies that the request expects a JSON response.
authorization: Bearer <JWT Token> A JSON Web Token (JWT) that authenticates the request. Replace <JWT Token> with a valid token.
content-type: application/json Specifies that the request body is in JSON format.

Request Body:

The request body should be in JSON format, containing an array of user objects to be added. Each user object contains the following fields:

name: string The name of the user.
email: string The email address of the user.
password: string (Optional) The password for the user.
confirm_password: string (Optional) The password confirmation for the user.
image: string (Optional) The URL of the user's profile image.
type: string The role or type of the user (e.g., user, admin).
notifications: boolean Specifies whether the user will receive notifications.
update: boolean Indicates if the user's information should be updated.
groups: array An array of group objects associated with the user. Each group contains:
- _id: string The group ID.
- workspace_id: object The workspace object associated with the group.
  - _id: string The workspace ID.
  - name: string The workspace name.
- name: string The group name.
- permissions: array An array of permission objects associated with the group.
token: string A valid authentication token (JWT) for adding users.

Example Request Body:

{
  "users": [
    {
      "name": "Matthew Kastner",
      "email": "[email protected]",
      "password": "",
      "confirm_password": "",
      "image": "",
      "type": "user",
      "notifications": false,
      "update": true,
      "groups": [
        {
          "_id": "756676a679549784d96514a2",
          "workspace_id": {
            "_id": "6567745179549784d96513ae",
            "name": "Internal Employees"
          },
          "name": "Basic Users",
          "permissions": [
            {
              "_id": "656faf7879549784d967e2bv",
              "page_id": "656faa7c79549784d967dfab",
              "filters": []
            }
          ]
        }
      ]
    }
  ],
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Method:

POST: Sends a request to add the specified user(s) to the system.

Example Request (Node.js):

const fetch = require('node-fetch');

const url = 'https://admin.<your-site>.com/api/users/add';
const options = {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'accept-language': 'en-US,en;q=0.9',
    'authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    users: [
      {
        name: "Matthew Kastner",
        email: "[email protected]",
        password: "",
        confirm_password: "",
        image: "",
        type: "user", // Options: ["user", "editor"", "admin"]
        notifications: false,
        update: true,
        groups: [ // Assign the user to a group within a workspace.
          {
            _id: "756676a679549784d96514a2", // Group _id
            workspace_id: {
              _id: "6567745179549784d96513ae",
              name: "Internal Employees"
            },
            name: "Basic Users", // Group name
            permissions: [
              {
                _id: "656faf7879549784d967e2bv",
                page_id: "656faa7c79549784d967dfab",
                filters: []
              }
            ]
          }
        ]
      }
    ],
    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Response:

The API will return a JSON response indicating the success or failure of the operation.

Success Response (200):

{
  "message": "User(s) added successfully",
  "status": "success"
}

Error Response (400/401):

{
  "message": "Invalid token or request body",
  "status": "error"
}

Authentication:

This API requires a valid JWT token for authentication. Ensure that the token is included in the authorization header as Bearer <JWT Token>.

Usage Notes:

The users array can contain multiple users to be added in one request.
Ensure that each user has a unique email address in the system.
A valid JWT token must be included in the authorization header, otherwise the request will fail.