Permissions

What are Permissions?

Permissions in DatAscend rule the actions which a role can execute on an specific object.

Definition and Purpose of Permissions within the System.

The following are the definitions for what actions can permissions handle and what objects can be managed with permissions.

Actions

Actions define what operations can be performed on objects.

Action	Description
Manage	Allows management of existing objects.
Create	Allows the creation of new objects.
Get	Allows viewing of existing objects.
Update	Allows modification of existing objects.
Delete	Allows removal of existing objects.
Get Own	Allows viewing only of existing objects created by the user
Update Own	Allows modification only of existing objects created by the user.
Delete Own	Allows removal only of existing objects created by the user.

Objects

Objects represent the resources or entities within the system that users can interact with, such as:

• Category Menus
• Relationships
• Datasources
• Structure
• Entities
• Domains
• Reports

How they are used to control access to resources, actions, or UI element?

Assigning an action to an object creates a permissions. Ej:

Assigning the Get action and the Entity object allows the role with that permission to view all entities of the system.

Relationship between permissions, roles, and users.

Users are assigned roles, and that role has permissions, which consist of an action on an object

Which Endpoints Interact with Permissions?

Get the permissions by object and role id

Retrieve the permissions by object and role id.

Endpoint:

GET /api/v1/data-studio/:roleId/permission/:objectId

parameters:

Name	Type	From	Description
roleId	number	path	id of the role
objectId	string	path	id of the object

Response example:

{
  "error": false,
  "status": 200,
  "message": "string",
  "errors": [{}],
  "data": [
    {
      "id": "0",
      "description": "(manage users on system)",
      "active": true,
      "objectId": "1",
      "actionId": "1",
      "actionItem": "Manage",
      "objectItem": "user",
      "objectType": "System",
      "allowed": true,
      "allowedSdate": "2024-10-23T06:00:00.000Z",
      "allowedEdate": "2024-10-23T06:00:00.000Z"
    }
  ],
  "pagination": {
    "hasPreviousPage": true,
    "hasNextPage": true,
    "previousPage": 0,
    "nextPage": 0,
    "recordsTotal": 0,
    "currentPage": 0,
    "startIndex": 0,
    "numPages": 0,
    "limit": 0
  }
}

Create permissions stored on role in studio by given object

Create permissions stored on a role in studio by a given object.

Endpoint:

POST /api/v1/data-studio/:roleId/permission

parameters:

Name	Type	From	Description
roleId	number	path	id of the role

Request example:

{
  "permissions": [
    {
      "id": "1",
      "description": "(manage users on system)",
      "active": true,
      "objectId": 3196,
      "actionId": 2,
      "actionItem": "Manage",
      "objectItem": "user",
      "objectType": "System"
    }
  ]
}

• id: id of the permission
• description: description of the permission
• active: If the permission is active
• objectId: id of the object
• actionId: id of the action
• actionItem: description of the action
• objectItem: item of the object
• objectType: type of the object

Response example:

{
  "error": false,
  "status": 200,
  "message": "string",
  "errors": [{}],
  "data": [
    {
      "id": "0",
      "description": "(manage users on system)",
      "active": true,
      "objectId": "1",
      "actionId": "1",
      "actionItem": "Manage",
      "objectItem": "user",
      "objectType": "System",
      "allowed": true,
      "allowedSdate": "2024-10-23T06:00:00.000Z",
      "allowedEdate": "2024-10-23T06:00:00.000Z"
    }
  ],
  "pagination": {
    "hasPreviousPage": true,
    "hasNextPage": true,
    "previousPage": 0,
    "nextPage": 0,
    "recordsTotal": 0,
    "currentPage": 0,
    "startIndex": 0,
    "numPages": 0,
    "limit": 0
  }
}

Router for getting entity permissions

Endpoint:

GET /api/v1/entities/{entity}/permissions

parameters:

Name	Type	From	Description
entity	string	path	id of the entity
version	string	query	version of the application

Router for setting entity permissions

Endpoint:

POST /api/v1/entities/{entity}/permissions

parameters:

Name	Type	From	Description
entity	string	path	id of the entity
version	string	query	version of the application

Request Body:

[
  {
    "permissionId": "string",
    "actionItem": "string",
    "actionId": "string",
    "roleItem": "string",
    "roleId": "string",
    "active": true
  }
]

Example Response:

{
  "status": 201,
  "error": false,
  "entityName": "string",
  "data": [
    {
      "permissionId": "string",
      "actionItem": "string",
      "actionId": "string",
      "roleItem": "string",
      "roleId": "string",
      "active": true
    }
  ]
}

Get permissions stored on role by given object

Retrieve permissions stored on a role in studio by a given object.

Endpoint:

 /api/v1/permissions/:roleId

Parameters:

Name	Type	From	Description
roleId`	number	path	id of the role

Response example:

{
error": false,
status": 200,
message": "string",
errors": [{}],
data": [
{
"name": "action",
"permission": true
}]
,
pagination": {
"hasPreviousPage": true,
"hasNextPage": true,
"previousPage": 0,
"nextPage": 0,
"recordsTotal": 0,
"currentPage": 0,
"startIndex": 0,
"numPages": 0,
"limit": 0
}}

Get all permissions stored on role

Endpoint:

/api/v1/permissions/all/:roleId

Parameters:

Name	Type	From	Description
roleId	number	path	id of the role

Response example:

{
error": false,
status": 200,
message": "string",
errors": [{}],
data": [
{
"id": "1",
"description": "(manage users on system)",
"active": true,
"objectId": "1",
"actionId": "1",
"actionItem": "Manage",
"objectItem": "user",
"objectType": "System",
"allowed": true,
"allowedSdate": "2024-10-23T06:00:00.000Z",
"allowedEdate": "2024-10-23T06:00:00.000Z"
}],
pagination": {
"hasPreviousPage": true,
"hasNextPage": true,
"previousPage": 0,
"nextPage": 0,
"recordsTotal": 0,
"currentPage": 0,
"startIndex": 0,
"numPages": 0,
"limit": 0}}

Get all available permissions stored on object

Retrieve all available permissions stored on a specific object.

Endpoint:

/api/v1/roles/permissions/:objectType/:objectItem

Parameters:

Name	Type	From	Description
objectType	string	path	type of the object
objectItem	string	path	id/name of the object
limit	number	query	limit for pagination
page	number	query	page for pagination

Response example:

{
error": false,
status": 200,
message": "string",
errors": [{}],
data": [
{
"id": "1",
"actionId": "1",
"objectId": "1",
"active": true,
"description": "admin"
}],
pagination": {
"hasPreviousPage": true,
"hasNextPage": true,
"previousPage": 0,
"nextPage": 0,
"recordsTotal": 0,
"currentPage": 0,
"startIndex": 0,
"numPages": 0,
"limit": 0
}}

Get permissions stored on role by given object

Retrieve permissions stored on a role for a given object.

Endpoint:

/api/v1/roles/:roleId/permissions/:objectType/:objectItem

Parameters:

Name	Type	From	Description
roleId	number	path	id of the role
objectType	string	path	type of the object
objectItem	string	path	id/name of the object
limit	number	query	limit for pagination
page	number	query	page for pagination

Response example:

{
error": false,
status": 200,
message": "string",
errors": [{}],
data": [
{
"roleId": "1",
"objectItem": "cattle",
"objectType": "Table",
"permissions": "1"
}],
pagination": {
"hasPreviousPage": true,
"hasNextPage": true,
"previousPage": 0,
"nextPage": 0,
"recordsTotal": 0,
"currentPage": 0,
"startIndex": 0,
"numPages": 0,
"limit": 0
}}

Overwrite permissions stored on role by given object

Overwrite permissions stored on a role for a given object.

Endpoint:

/api/v1/roles/:roleId/permissions

Parameters:

Name	Type	From	Description
roleId	number	path	id of the role

Request example:

{
objectItem": "cattle",
objectType": "Table",
permissions": 1
}

**Response example:**

{
error": false,
status": 200,
message": "string",
errors": [{}],
data": [
{
"roleId": "1",
"objectItem": "cattle",
"objectType": "Table",
"permissions": "1",
"id": "1",
"actionId": "1",
"objectId": "1",
"active": true,
"description": "Permission applied in object"
}]
,
pagination": {
"hasPreviousPage": true,
"hasNextPage": true,
"previousPage": 0,
"nextPage": 0,
"recordsTotal": 0,
"currentPage": 0,
"startIndex": 0,
"numPages": 0,
"limit": 0
}}

Get information about current user (including permissions)

Endpoint:

/api/v1/users/me

Response example:

{
error": false,
status": 200,
message": "string",
errors": [{}],
data": {
"id": "1",
"contactId": 1,
"email": "email@email.co",
"username": "Administrador",
"createdAt": "2022-01-05T16:27:16.560Z",
"updatedAt": "2022-01-05T16:27:16.560Z",
"active": true,
"login": true,
"loginInfo": {
"message": "status_messages.user_logged_in_successfully",
"remoteAddr": "127.0.0.1",
"userAgent": "Mozilla/5.0"
},
"roles": [
{
"id": "1",
"name": "Administrador",
"dashboardCustomQuery": "2"
}
],
"permissions": [
{
"actionItem": "string",
"domain": "string",
"objectItem": "string",
"role": "string",
"roleId": "string"
}
],
"domains": [
{
"id": 0,
"name": "Any domain",
"description": "Any description",
"subDomains": ["string"],
"parentId": 0,
"createdAt": "1970-01-01T00:00:00Z",
"updatedAt": "1970-01-01T00:00:00Z",
"active": true
}
],
"isAdmin": true,
"menu": [
{
"category": "category",
"menuOptions": [
{
"menuId": "2",
"menuName": "test",
"entity": "animal"
}
]
}
]
,
pagination": {
"hasPreviousPage": true,
"hasNextPage": true,
"previousPage": 0,
"nextPage": 0,
"recordsTotal": 0,
"currentPage": 0,
"startIndex": 0,
"numPages": 0,
"limit": 0}}}