API Guide - Role

  • Updated on Apr 27, 2022

List roles

Fetches a list of roles in your Banyan organization.

Review the Role Spec Syntax for more information on the Role data structures.

HTTP Request

GET /v1/security_roles

URL Parameters

N/A

Query Parameters

Parameter Format Description
RoleID String The ID of the Role to retrieve

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

N/A

Status Codes and Errors

Value Description
200 OK

Response Headers

N/A

HTTP Response Body

[
  {
    "RoleID": "398ccd36-c4f8-4229-af4d-eb2caa12af4f",
    "RoleName": "kclient2",
    "RoleSpec": "{\n\t\"kind\": \"BanyanRole\",\n\t\"apiVersion\": \"rbac.banyanops.com/v1\",\n\t\"type\": \"attribute\",\n\t\"metadata\": {\n\t\t\"name\": \"kclient2\",\n\t\t\"description\": \"kafka client 2\"\n\t},\n\t\"spec\": {\n\t\t\"label_selector\": [\n\t\t\t{\n\t\t\t\t\"com.banyanops.client\": \"kclient2\"\n\t\t\t}\n\t\t]\n\t}\n}",
    "CreatedBy": "tarun+kubedemo@banyanops.com",
    "CreatedAt": 1493950047,
    "LastUpdatedBy": "tarun+kubedemo@banyanops.com",
    "LastUpdatedAt": 1493950047,
    "Description": "kafka client 2",
    "RoleType": "attribute",
    "RoleVersion": 0,
    "DeletedBy": "",
    "DeletedAt": "",
    "Enabled": "TRUE"
  },
  {
    "RoleID": "725912d2-6f8e-4df1-b73f-d8d3a2e99706",
    "RoleName": "NormalClientAttrRole",
    "RoleSpec": "{\n\t\"kind\": \"BanyanRole\",\n\t\"apiVersion\": \"rbac.banyanops.com/v1\",\n\t\"type\": \"attribute\",\n\t\"metadata\": {\n\t\t\"name\": \"NormalClientAttrRole\",\n\t\t\"description\": \"Normal attribute-based client role (without any super privileges)\"\n\t},\n\t\"spec\": {\n\t\t\"container_fqdn\": [\n\t\t\t\"k8s-cluster1.namespace2.apache2\",\n\t\t\t\"k8s-cluster1.namespace2.wordpress\"\n\t\t],\n\t\t\"image\": [\n\t\t\t\"registry.xyz.com/billing/apache:*\",\n\t\t\t\"registry.xyz.com/payment/wordpress:latest\"\n\t\t],\n\t\t\"_comment-label-spec1\": \"AND over selectors: selector1, selector2, ...; OR inside a selector: {'x':'aa*|*b|!c*', 'y':'cd'}\",\n\t\t\"_comment-label-spec2\": \"Wildcard (*) beginning or end of a selector; NOT (!): only at the beginning of selector\",\n\t\t\"label_selector\": [\n\t\t\t{\n\t\t\t\t\"com.banyanops.servicetype\": \"prod\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"com.xyz.app\": \"!test-app\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"com.banyanops.servicename\": \"clustername.ns1.frontend*|*apiserver\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"com.xyz.projectid\": \"4456-6675\",\n\t\t\t\t\"com.xyz.groupid\": \"556675\"\n\t\t\t}\n\t\t],\n\t\t\"ips\": [\n\t\t\t\"10.20.30.0/24\",\n\t\t\t\"10.20.31.41/2\"\n\t\t]\n\t}\n}",
    "CreatedBy": "tarun+marko@banyanops.com",
    "CreatedAt": 1489063881,
    "LastUpdatedBy": "tarun+marko@banyanops.com",
    "LastUpdatedAt": 1495027145,
    "Description": "Normal attribute-based client role (without any super privileges)",
    "RoleType": "attribute",
    "RoleVersion": 1,
    "DeletedBy": "",
    "DeletedAt": "",
    "Enabled": "FALSE"
  }
]

Create a new role or update an existing role

HTTP Request

POST /v1/insert_security_role

URL Parameters

N/A

Query Parameters

N/A

Request Headers

Authorization: Bearer $AUTHTOKEN, ContentType: application/json

Request Body

JSON string with the Role Spec

Sample JSON body:

{
   "kind": "BanyanRole",
   "apiVersion": "rbac.banyanops.com/v1",
   "type": "attribute",
   "metadata": {
      "name": "container-role",
      "description": "Attribute-based client role based on image and labels",
      "tags": {
        "template": "CUSTOM"
      }
   },
   "spec": {
      "repo_tag":[
         "registry.xyz.com/billing/apache:*",
      ],
      "label_selector":[
         {
            "appname":"frontend*"
         },
         {
            "com.banyanops.procname":"helloworld"
         },
      ],
       "platform": [
            "macOS",
            "windows",
            "linux"
        ],
        "service_account":[
            "service_account1",
            "service_account2",
            "service_account3"
        ]
   }
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request

Response Headers

N/A

Response Body

If a Role with the name doesn’t already exist, a new Role is created and a RoleID is returned.

{
    "RoleID": "f2d4761f-f947-49b0-990a-aebc342db40a",
    "RoleName": "container-role",
    "RoleSpec": "{\"kind\":\"BanyanRole\",\"apiVersion\":\"rbac.banyanops.com/v1\",\"type\":\"origin\",\"metadata\":{\"id\":\"\",\"name\":\"container-role\",\"description\":\"test admin role\",\"tags\":{\"template\":\"USER\"}},\"spec\":{\"container_fqdn\":null,\"image\":null,\"repo_tag\":null,\"label_selector\":null,\"service_account\":[\"service_account1\",\"service_account2\",\"service_account3\"],\"group\":[],\"email\":[],\"device_ownership\":[],\"platform\":[\"macOS\",\"Windows\"],\"known_device_only\":false,\"mdm_present\":false}}",
    "CreatedBy": "puja.thanekar@joshsoftware.com",
    "CreatedAt": 1645617427367342380,
    "LastUpdatedBy": "puja.thanekar@joshsoftware.com",
    "LastUpdatedAt": 1645700863881625505,
    "Description": "test admin role",
    "RoleType": "origin",
    "RoleVersion": 6,
    "DeletedBy": "",
    "DeletedAt": 0,
    "Enabled": "TRUE"
}

If a Role with the name does exist, it is updated.

Delete a role

HTTP Request

DELETE /v1/delete_security_role

URL Parameters

N/A

Query Parameters

Parameter Format Description
RoleID String The ID of the Role to delete

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

N/A

Status Codes and Errors

Value Description
200 OK

Response Headers

N/A

HTTP Response Body

N/A

Enables a security role

This end point enables a security role and then sends the notification to all Shields of its Organization.

HTTP Request

POST /v1/enable_security_role?RoleID=R

URL Parameters

NA

Query Parameters

Parameter Format Description
RoleID String The ID of the role which needs to be enabled.

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

NA

Status Codes and Errors

Value Description
200 OK
400 Bad request
401 Unauthorized
500 Internal Server Error

Response Headers

N/A

Response Body

{
    "Message": "Role 354033eb-9b59-4e85-9bde-b56f10201e22 enabled successfully"
}

Disables a security role

This endpoint disables a security role and then sends the notification to all Shields of its Organization.

HTTP Request

POST /v1/disable_security_role?RoleID=R

URL Parameters

NA

Query Parameters

Parameter Format Description
RoleID String The ID of the role which needs to be disabled

Request Headers

Authorization: Bearer $AUTHTOKEN

Request Body

NA

Status Codes and Errors

Value Description
200 OK
400 Bad request
401 Unauthorized
500 Internal Server Error

Response Headers N/A

Response Body

{
    "Message": "Role 354033eb-9b59-4e85-9bde-b56f10201e22 disabled successfully"
}