Permissions API (Legacy)

Deprecated

This endpoint refers to the legacy permission model. The current system uses IAM-style Policies with service:action action strings.

See Policies API for the current reference.

The endpoints below are preserved for backwards compatibility. For new integrations, use the Policies API and Groups API instead.

List Permissions

Returns all permissions.

GET/v1/permissions

Required Permission: read

Example Request:

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

Response: 200 OK

{
  "total": 10,
  "quantity": 10,
  "records": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Manage Users",
      "description": "Full access to user management",
      "target": {
        "company_id": "*",
      },
      "actions": ["read", "create", "update", "delete"],
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

---

Get Permission

Returns a single permission by ID.

GET/v1/permissions/:id

Required Permission: read

Example Request:

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

---

Create Permission

Creates a new permission.

POST/v1/permissions

Required Permission: create

Request Body:

Field	Type	Required	Description
name	string	Yes	Permission name (min 3 chars)
description	string	Yes	Description (min 10 chars)
target	object	Yes	Target scope object
actions	string[]	Yes	Allowed actions (min 1)

Target Object:

Field	Type	Required	Description
company_id	string	Yes	Company ID or *
service_name	string	No	Service name (e.g., billing)
service_id	string	No	Resource ID or *

Actions:

Value	Description
read	View resources
create	Create resources
update	Modify resources
delete	Remove resources
*	All actions

Example Request:

curl -X POST https://api.console.solucao42.com.br/v1/permissions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing Manager",
    "description": "Full access to billing features company-wide",
    "target": {
      "company_id": "507f1f77bcf86cd799439001",
      "service_name": "billing"
    },
    "actions": ["read", "create", "update"]
  }'

Response: 201 Created

{
  "_id": "507f1f77bcf86cd799439015",
  "name": "Billing Manager",
  "description": "Full access to billing features company-wide",
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "teamId": "*",
    "service_name": "billing"
  },
  "actions": ["read", "create", "update"],
  "created_at": "2024-03-01T10:30:00.000Z"
}

---

Update Permission

Updates an existing permission.

PUT/v1/permissions/:id

Required Permission: update

Request Body:

All fields are optional. Only include what you want to change.

Field	Type	Description
name	string	New name
description	string	New description
target	object	New target scope
actions	string[]	New allowed actions

Example Request:

curl -X PUT https://api.console.solucao42.com.br/v1/permissions/PERMISSION_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": ["read"]
  }'

---

Delete Permission

Deletes a permission.

DELETE/v1/permissions/:id

Required Permission: delete

Example Request:

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

Response: 204 No Content

---

Permission Object

Field	Type	Description
_id	string	Unique identifier
name	string	Permission name
description	string	Description
target	object	Scope definition
actions	string[]	Allowed actions
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

---

Target Patterns

Company-Wide Access

Company-specific access:

{
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
  }
}

Service-Specific Access

A specific service company-wide:

{
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "service_name": "billing"
  }
}

Resource-Specific Access

A specific resource in a service:

{
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "service_name": "projects",
    "service_id": "507f1f77bcf86cd799439003"
  }
}

Global Access (Super Admin)

All companies (use with extreme caution):

{
  "target": {
    "company_id": "*",
  }
}

---

Permission Examples

User Manager

{
  "name": "User Manager",
  "description": "Can view and manage all users in the company",
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
  },
  "actions": ["read", "create", "update"]
}

Report Viewer

{
  "name": "Report Viewer",
  "description": "Read-only access to reports",
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "teamId": "*",
    "service_name": "reports"
  },
  "actions": ["read"]
}

Department Administrator

{
  "name": "Sales Admin",
  "description": "Full admin access for Sales department",
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "service_name": "sales"
  },
  "actions": ["*"]
}

Billing Read-Only

{
  "name": "Billing Viewer",
  "description": "Can view billing information but not modify",
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "service_name": "billing"
  },
  "actions": ["read"]
}

---

ID Format Validation

IDs in the target object must be either:

• A valid MongoDB ObjectId: ^[a-f0-9]{24}$
• The wildcard character: *

Valid Examples:

• 507f1f77bcf86cd799439001
• *

Invalid Examples:

• my-company
• 123
• null

---

Code Examples

JavaScript

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

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

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

// Delete permission
async function deletePermission(token, permissionId) {
  const response = await fetch(`${API_URL}/v1/permissions/${permissionId}`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${token}` },
  });
  return response.ok;
}

// Usage
const billingPermission = await createPermission(token, {
  name: 'Billing Manager',
  description: 'Manage billing company-wide',
  target: {
    company_id: 'company-id',
    service_name: 'billing'
  },
  actions: ['read', 'create', 'update']
});

console.log(`Created permission: ${billingPermission._id}`);

cURL

TOKEN="your-jwt-token"

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

# Create permission
curl -s -X POST "https://api.console.solucao42.com.br/v1/permissions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing Manager",
    "description": "Manage billing company-wide",
    "target": {
      "company_id": "507f1f77bcf86cd799439001",
      "service_name": "billing"
    },
    "actions": ["read", "create", "update"]
  }' | jq

# Update permission
curl -s -X PUT "https://api.console.solucao42.com.br/v1/permissions/PERMISSION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"actions": ["read"]}' | jq

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

---

Best Practices

1. Use descriptive names - Billing Manager is better than Permission 1
2. Be specific - Narrow scopes are safer than wildcards
3. Document permissions - Include clear descriptions
4. Audit changes - Track who creates/modifies permissions
5. Test before production - Verify permissions work as expected