Permissions API

Endpoints for managing fine-grained permissions. Permissions define what actions can be performed on which resources.

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