Users API

Endpoints for managing users, invitations, and group assignments.

List Users

Returns all users in the company.

GET/v1/users

Required Permission: user:read

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Items per page (max: 100)
`include`	string	-	Set to `groups` for expanded group data

Example Request:

curl "https://api.console.solucao42.com.br/v1/users?include=groups" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 200 OK

{
  "total": 25,
  "quantity": 20,
  "records": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "email": "[email protected]",
      "name": "John Doe",
      "company_id": "507f1f77bcf86cd799439012",
      "status": "active",
      "group_ids": ["admin-group"],
      "groups": [
        {
          "_id": "admin-group",
          "name": "Administrators",
          "slug": "administrators"
        }
      ],
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Get User

Returns a single user by ID.

GET/v1/users/:id

Required Permission: user:read

Example Request:

curl https://api.console.solucao42.com.br/v1/users/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 200 OK

{
  "_id": "507f1f77bcf86cd799439011",
  "email": "[email protected]",
  "name": "John Doe",
  "company_id": "507f1f77bcf86cd799439012",
  "status": "active",
  "teams": ["default-team"],
  "group_ids": ["admin-group"],
  "created_at": "2024-01-15T10:30:00.000Z"
}

Invite User

Invites a new user to the company. They'll receive an email to set their password.

POST/v1/users/invite

Required Permission: user:update

Request Body:

Field	Type	Required	Description
`email`	string	Yes	User's email address
`team_ids`	string[]	No	Teams to assign
`group_ids`	string[]	No	Groups to assign

Example Request:

curl -X POST https://api.console.solucao42.com.br/v1/users/invite \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "group_ids": ["editors"]
  }'

Response: 201 Created

{
  "_id": "507f1f77bcf86cd799439015",
  "email": "[email protected]",
  "company_id": "507f1f77bcf86cd799439012",
  "status": "invited",
  "teams": ["default-team"],
  "group_ids": ["editors"],
  "invitation_expires_at": "2024-03-08T10:30:00.000Z",
  "created_at": "2024-03-01T10:30:00.000Z"
}

Errors:

Status	Error Code	Description
400	`USER_EMAIL_DUPLICATE`	Email already exists
422	`VALIDATION_ERROR`	Invalid email format

Accept Invitation

Accepts an invitation and sets the user's password. No authentication required.

POST/v1/users/accept-invitation

Request Body:

Field	Type	Required	Description
`token`	string	Yes	Invitation token from email
`password`	string	Yes	New password (min 12 chars)

Example Request:

curl -X POST https://api.console.solucao42.com.br/v1/users/accept-invitation \
  -H "Content-Type: application/json" \
  -d '{
    "token": "invitation-token-from-email",
    "password": "SecurePassword123!"
  }'

Response: 200 OK

{
  "success": true,
  "user": {
    "_id": "507f1f77bcf86cd799439015",
    "email": "[email protected]",
    "status": "active"
  }
}

Errors:

Status	Error Code	Description
400	`INVALID_INVITATION_TOKEN`	Token expired or invalid
422	`VALIDATION_ERROR`	Password doesn't meet requirements

Request Password Reset

Sends a password reset email. No authentication required.

POST/v1/users/reset-password/request

Request Body:

Field	Type	Required	Description
`email`	string	Yes	User's email address

Example Request:

curl -X POST https://api.console.solucao42.com.br/v1/users/reset-password/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Response: 200 OK

{
  "success": true,
  "message": "If the email exists, a reset link has been sent"
}

Security Note

The response is always the same regardless of whether the email exists. This prevents email enumeration attacks.

Activate User

Activates a deactivated user.

POST/v1/users/:id/activate

Required Permission: user:update

Example Request:

curl -X POST https://api.console.solucao42.com.br/v1/users/USER_ID/activate \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 200 OK

{
  "_id": "507f1f77bcf86cd799439011",
  "email": "[email protected]",
  "status": "active"
}

Deactivate User

Deactivates a user. They won't be able to log in.

POST/v1/users/:id/deactivate

Required Permission: user:update

Example Request:

curl -X POST https://api.console.solucao42.com.br/v1/users/USER_ID/deactivate \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 200 OK

{
  "_id": "507f1f77bcf86cd799439011",
  "email": "[email protected]",
  "status": "inactive"
}

Errors:

Status	Error Code	Description
400	`CANNOT_DEACTIVATE_SELF`	You cannot deactivate yourself

Add Groups to User

Adds groups to a user (appends to existing).

POST/v1/users/:id/groups

Required Permission: user:update

Request Body:

Field	Type	Required	Description
`group_ids`	string[]	Yes	Group IDs to add (min 1)

Example Request:

curl -X POST https://api.console.solucao42.com.br/v1/users/USER_ID/groups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": ["editors", "viewers"]
  }'

Response: 200 OK

Returns the updated user object.

Replace User Groups

Replaces all groups of a user.

PUT/v1/users/:id/groups

Required Permission: user:update

Request Body:

Field	Type	Required	Description
`group_ids`	string[]	Yes	New group IDs (replaces all)

Example Request:

curl -X PUT https://api.console.solucao42.com.br/v1/users/USER_ID/groups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": ["managers"]
  }'

Remove Groups from User

Removes specific groups from a user.

DELETE/v1/users/:id/groups

Required Permission: user:update

Request Body:

Field	Type	Required	Description
`group_ids`	string[]	Yes	Group IDs to remove

Example Request:

curl -X DELETE https://api.console.solucao42.com.br/v1/users/USER_ID/groups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": ["viewers"]
  }'

User Object

Field	Type	Description
`_id`	string	Unique identifier
`email`	string	Email address (unique per company)
`name`	string	Display name
`company_id`	string	Parent company ID
`status`	string	`invited`, `active`, or `inactive`
`group_ids`	string[]	Group IDs assigned to user
`groups`	object[]	Expanded group objects (when `include=groups`)
`created_at`	string	ISO 8601 creation timestamp

User Status

Status	Description
`invited`	User received invitation, hasn't accepted
`active`	User is active and can log in
`inactive`	User is deactivated, cannot log in

Code Examples

JavaScript
cURL

const API_URL = 'https://api.console.solucao42.com.br';

// List users with groups
async function listUsers(token) {
  const response = await fetch(`${API_URL}/v1/users?include=groups`, {
    headers: { 'Authorization': `Bearer ${token}` },
  });
  return response.json();
}

// Invite user
async function inviteUser(token, email, group_ids = []) {
  const response = await fetch(`${API_URL}/v1/users/invite`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email, group_ids }),
  });
  return response.json();
}

// Manage user groups
async function setUserGroups(token, userId, group_ids) {
  const response = await fetch(`${API_URL}/v1/users/${userId}/groups`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ group_ids }),
  });
  return response.json();
}

// Deactivate user
async function deactivateUser(token, userId) {
  const response = await fetch(`${API_URL}/v1/users/${userId}/deactivate`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
  });
  return response.json();
}

TOKEN="your-jwt-token"

# List users
curl -s "https://api.console.solucao42.com.br/v1/users?include=groups" \
  -H "Authorization: Bearer $TOKEN" | jq

# Invite user
curl -s -X POST "https://api.console.solucao42.com.br/v1/users/invite" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","group_ids":["editors"]}' | jq

# Add groups
curl -s -X POST "https://api.console.solucao42.com.br/v1/users/USER_ID/groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"group_ids":["managers"]}' | jq

# Deactivate user
curl -s -X POST "https://api.console.solucao42.com.br/v1/users/USER_ID/deactivate" \
  -H "Authorization: Bearer $TOKEN" | jq

List Users​

Get User​

Invite User​

Accept Invitation​

Request Password Reset​

Activate User​

Deactivate User​

Add Groups to User​

Replace User Groups​

Remove Groups from User​

User Object​

User Status​

Code Examples​

List Users

Get User

Invite User

Accept Invitation

Request Password Reset

Activate User

Deactivate User

Add Groups to User

Replace User Groups

Remove Groups from User

User Object

User Status

Code Examples