Groups API

Endpoints for managing groups and their permissions. Groups are used to implement role-based access control (RBAC).

List Groups

Returns all groups in the company.

GET/v1/groups

Required Permission: read

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Items per page (max: 100)
`include_global`	boolean	true	Include system/global groups

Example Request:

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

Response: 200 OK

{
  "total": 4,
  "quantity": 4,
  "records": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Administrators",
      "slug": "administrators",
      "description": "Full system access",
      "company_id": "507f1f77bcf86cd799439012",
      "is_global": false,
      "roles": [
        {
          "name": "Admin",
          "target": "*",
          "actions": ["*"]
        }
      ],
      "permissionIds": [],
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Get Group

Returns a single group by ID.

GET/v1/groups/:id

Required Permission: read

Example Request:

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

Create Group

Creates a new group.

POST/v1/groups

Required Permission: create

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Group name (min 2 chars)
`slug`	string	Yes	URL-safe identifier
`description`	string	Yes	Description (min 10 chars)
`roles`	object[]	No	Array of role objects
`permissionIds`	string[]	No	Permission IDs to assign

Role Object:

Field	Type	Required	Description
`name`	string	Yes	Role name
`target`	string	Yes	Resource target (`*` for all)
`actions`	string[]	Yes	Allowed actions (min 1)

Example Request:

curl -X POST https://api.console.solucao42.com.br/v1/groups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Content Editors",
    "slug": "content-editors",
    "description": "Can create and edit content, but not delete",
    "roles": [
      {
        "name": "Content Manager",
        "target": "content",
        "actions": ["read", "create", "update"]
      }
    ]
  }'

Response: 201 Created

{
  "_id": "507f1f77bcf86cd799439015",
  "name": "Content Editors",
  "slug": "content-editors",
  "description": "Can create and edit content, but not delete",
  "company_id": "507f1f77bcf86cd799439012",
  "is_global": false,
  "roles": [
    {
      "name": "Content Manager",
      "target": "content",
      "actions": ["read", "create", "update"]
    }
  ],
  "permissionIds": [],
  "created_at": "2024-03-01T10:30:00.000Z"
}

Slug Pattern:

The slug must match: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Valid: editors, content-editors, team-a-editors Invalid: Editors, content_editors, content--editors

Update Group

Updates an existing group.

PUT/v1/groups/:id

Required Permission: update

Request Body:

Field	Type	Required	Description
`name`	string	No	New group name
`slug`	string	No	New slug
`description`	string	No	New description

Example Request:

curl -X PUT https://api.console.solucao42.com.br/v1/groups/GROUP_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Editors",
    "description": "Experienced content editors with expanded access"
  }'

Delete Group

Deletes a group.

DELETE/v1/groups/:id

Required Permission: delete

Example Request:

curl -X DELETE https://api.console.solucao42.com.br/v1/groups/GROUP_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content

Errors:

Status	Error Code	Description
400	`CANNOT_DELETE_GLOBAL`	Cannot delete system groups

Add Permissions

Adds permissions to a group (appends to existing).

POST/v1/groups/:id/permissions

Required Permission: update

Request Body:

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

Example Request:

curl -X POST https://api.console.solucao42.com.br/v1/groups/GROUP_ID/permissions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionIds": ["perm-1", "perm-2"]
  }'

Replace Permissions

Replaces all permissions of a group.

PUT/v1/groups/:id/permissions

Required Permission: update

Request Body:

Field	Type	Required	Description
`permissionIds`	string[]	Yes	New permission IDs

Example Request:

curl -X PUT https://api.console.solucao42.com.br/v1/groups/GROUP_ID/permissions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionIds": ["perm-3", "perm-4"]
  }'

Remove Permissions

Removes specific permissions from a group.

DELETE/v1/groups/:id/permissions

Required Permission: update

Request Body:

Field	Type	Required	Description
`permissionIds`	string[]	Yes	Permission IDs to remove

Example Request:

curl -X DELETE https://api.console.solucao42.com.br/v1/groups/GROUP_ID/permissions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionIds": ["perm-1"]
  }'

Group Object

Field	Type	Description
`_id`	string	Unique identifier
`name`	string	Display name
`slug`	string	URL-safe identifier
`description`	string	Group description
`company_id`	string	Parent company ID
`is_global`	boolean	Whether it's a system group
`roles`	object[]	Role definitions
`permissionIds`	string[]	Assigned permission IDs
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last update timestamp

Role Object

Field	Type	Description
`name`	string	Role name
`target`	string	Resource target (e.g., `users`, `content`, `*`)
`actions`	string[]	Allowed actions: `read`, `create`, `update`, `delete`, `*`

Common Group Patterns

Full Access Admin

{
  "name": "Administrators",
  "slug": "administrators",
  "description": "Full system access for administrators",
  "roles": [
    {
      "name": "Admin",
      "target": "*",
      "actions": ["*"]
    }
  ]
}

Read-Only Viewer

{
  "name": "Viewers",
  "slug": "viewers",
  "description": "Read-only access to all resources",
  "roles": [
    {
      "name": "Viewer",
      "target": "*",
      "actions": ["read"]
    }
  ]
}

Resource-Specific Editor

{
  "name": "Content Editors",
  "slug": "content-editors",
  "description": "Can manage content but not other resources",
  "roles": [
    {
      "name": "Content Manager",
      "target": "content",
      "actions": ["read", "create", "update", "delete"]
    },
    {
      "name": "User Viewer",
      "target": "users",
      "actions": ["read"]
    }
  ]
}

Code Examples

JavaScript
cURL

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

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

// Create group
async function createGroup(token, group) {
  const response = await fetch(`${API_URL}/v1/groups`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(group),
  });
  return response.json();
}

// Add permissions to group
async function addPermissions(token, groupId, permissionIds) {
  const response = await fetch(`${API_URL}/v1/groups/${groupId}/permissions`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ permissionIds }),
  });
  return response.json();
}

// Usage
const newGroup = await createGroup(token, {
  name: 'Editors',
  slug: 'editors',
  description: 'Content editors with limited access',
  roles: [
    { name: 'Editor', target: 'content', actions: ['read', 'update'] }
  ]
});

await addPermissions(token, newGroup._id, ['perm-1', 'perm-2']);

TOKEN="your-jwt-token"

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

# Create group
curl -s -X POST "https://api.console.solucao42.com.br/v1/groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Editors",
    "slug": "editors",
    "description": "Content editors with limited access",
    "roles": [{"name": "Editor", "target": "content", "actions": ["read", "update"]}]
  }' | jq

# Add permissions
curl -s -X POST "https://api.console.solucao42.com.br/v1/groups/GROUP_ID/permissions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permissionIds": ["perm-1", "perm-2"]}' | jq

# Delete group
curl -s -X DELETE "https://api.console.solucao42.com.br/v1/groups/GROUP_ID" \
  -H "Authorization: Bearer $TOKEN"

List Groups​

Get Group​

Create Group​

Update Group​

Delete Group​

Add Permissions​

Replace Permissions​

Remove Permissions​

Group Object​

Role Object​

Common Group Patterns​

Full Access Admin​

Read-Only Viewer​

Resource-Specific Editor​

Code Examples​

List Groups

Get Group

Create Group

Update Group

Delete Group

Add Permissions

Replace Permissions

Remove Permissions

Group Object

Role Object

Common Group Patterns

Full Access Admin

Read-Only Viewer

Resource-Specific Editor

Code Examples