API Guide - Service

List services

Fetches a list of services in your Banyan organization.

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

HTTP Request

GET /registered_services

URL Parameters

N/A

Query Parameters

Parameter Format Description
ServiceID String The ID of the Service 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

[
  {
    "ServiceID": "sdsd1.scalemesos0.bnn",
    "ServiceName": "sdsd1.scalemesos0.bnn",
    "ClusterName": "scalemesos0",
    "ServiceType": "user-defined",
    "ServiceDiscovery": "",
    "ServiceVersion": 11,
    "Description": "sdsd 123",
    "CreatedAt": 2147483647,
    "CreatedBy": "gautam+scalingtest@joshsoftware.com",
    "LastUpdatedAt": 2147483647,
    "LastUpdatedBy": "gautam+scalingtest@joshsoftware.com",
    "DeletedAt": 0,
    "DeletedBy": "",
    "External": "",
    "OIDCEnabled": "FALSE",
    "OIDCClientSpec": "{\"trust_auth\":\"https://scalingtest.trust.bnntest.com:8443/auth\",\"trust_cb\":\"https://a.b/bnn_trust_cb\",\"client_id\":\"-M3SNv4aTayBRdGOOjs3Kg\",\"client_secret\":\"YrbAeIQjpeJT8Cx2Bl24rCM50CT1oe7gQTw3WjOSwM4\"}",
    "ServiceSpec": "{\"kind\":\"BanyanService\",\"apiVersion\":\"service.banyanops.com/v1\",\"type\":\"user-defined\",\"metadata\":{\"name\":\"sdsd1\",\"description\":\"sdsd 123\",\"cluster\":\"scalemesos0\",\"user_facing\": true, \"protocol\": \"HTTP\", \"domain\": \"https:\/\/a.b\", \"port\": \"502\"},\"spec\":{\"attributes\":{\"addresses\":[]},\"cert_settings\":{\"dns_names\":[],\"custom_tls_cert\":{\"app_cert\":\"\",\"app_key\":\"\"}},\"http_settings\":{\"Enabled\":true,\"oidc_settings\":{\"enabled\":false,\"service_domain_name\":\"https://a.b\",\"post_auth_redirect_path\":\"\",\"api_path\":\"\",\"suppress_device_trust_verification\":true},\"http_health_check\":{\"Enabled\":false,\"addresses\":null,\"method\":\"\",\"path\":\"\",\"user_agent\":\"\",\"from_address\":null,\"https\":false},\"http_redirect\":{\"Enabled\":false,\"addresses\":null,\"from_address\":null,\"url\":\"\",\"status_code\":0}}}}",
    "UserFacing": "TRUE",
    "Protocol": "http",
    "Domain": "a.b",
    "Port": 502,
    "Enabled": "TRUE"
  },
  {
    "ServiceID": "test-jg.scalemesos0.bnn",
    "ServiceName": "test-jg.scalemesos0.bnn",
    "ClusterName": "scalemesos0",
    "ServiceType": "unknown",
    "ServiceDiscovery": "",
    "ServiceVersion": 1,
    "Description": "test",
    "CreatedAt": 2147483647,
    "CreatedBy": "jayanth+scalingtest@banyanops.com",
    "LastUpdatedAt": 2147483647,
    "LastUpdatedBy": "jayanth+scalingtest@banyanops.com",
    "DeletedAt": 0,
    "DeletedBy": "",
    "External": "",
    "OIDCEnabled": "TRUE",
    "OIDCClientSpec": "{\"trust_auth\":\"https://scalingtest.trust.bnntest.com:8443/auth\",\"trust_cb\":\"https://jira.bnntest.com:8900/bnn_trust_cb\",\"client_id\":\"JUctS2NN_Vh6NwkMVj7ITg\",\"client_secret\":\"NY8N0dcF46Ml2EQYcPaeH_mOwCUB_jk5mrlHscuA0gQ\"}",
    "ServiceSpec": "{\"kind\":\"BanyanService\",\"apiVersion\":\"service.banyanops.com/v1\",\"type\":\"unknown\",\"metadata\":{\"name\":\"test-jg\",\"description\":\"test\",\"cluster\":\"scalemesos0\",\"user_facing\": true, \"protocol\": \"HTTP\", \"domain\": \"https:\/\/jira.bnntest.com\", \"port\": \"8900\"},\"spec\":{\"attributes\":{\"addresses\":[]},\"cert_settings\":{\"dns_names\":[],\"custom_tls_cert\":{\"app_cert\":\"\",\"app_key\":\"\"}},\"http_settings\":{\"enabled\":true,\"oidc_settings\":{\"enabled\":true,\"service_domain_name\":\"https://jira.bnntest.com:8900\",\"post_auth_redirect_path\":\"/\",\"api_path\":\"/api\",\"suppress_device_trust_verification\":true},\"http_health_check\":{\"enabled\":false,\"addresses\":null,\"method\":\"\",\"path\":\"\",\"user_agent\":\"\",\"from_address\":null,\"https\":false},\"http_redirect\":{\"enabled\":false,\"addresses\":null,\"from_address\":null,\"url\":\"\",\"status_code\":0}}}}",
    "UserFacing": "TRUE",
    "Protocol": "http",
    "Domain": "jira.bnntest.com",
    "Port": 8900,
    "Enabled": "FALSE"
  }
]

Create a new service or update an existing service

HTTP Request

POST /insert_registered_service

URL Parameters

N/A

Query Parameters

N/A

Request Headers

Authorization: Bearer $AUTHTOKEN, ContentType: application/json

Request Body

JSON string with the Service Spec

Sample JSON body:

{
    "kind": "BanyanService",
    "apiVersion": "rbac.banyanops.com/v1",
    "type": "origin",
    "metadata": {
        "name": "example_web_service",
        "description": "web service example ",
        "cluster": "release-rc",
        "tags": {
            "template": "WEB_USER",
            "user_facing": "true",
            "protocol": "https",
            "domain": "example.bnntest.com",
            "port": "443",
            "icon": "cloud",
            "service_app_type": "WEB"
        }
    },
    "spec": {
        "attributes": {
            "frontend_addresses": [
                {
                    "cidr": "",
                    "port": "443"
                }
            ],
            "host_tag_selector": [
                {
                    "com.banyanops.hosttag.site_name": "deva-net-mar4"
                }
            ],
            "tls_sni": [
                "example.bnntest.com"
            ]
        },
        "backend": {
            "target": {
                "name": "34.70.156.134",
                "port": "433",
                "tls": true,
                "tls_insecure": true,
                "client_certificate": false
            },
            "dns_overrides": {},
            "whitelist": [],
            "http_connect": false,
            "allow_patterns": []
        },
        "cert_settings": {
            "letsencrypt": true,
            "dns_names": [
                "example.bnntest.com"
            ],
            "custom_tls_cert": {
                "enabled": false,
                "cert_file": "",
                "key_file": ""
            }
        },
        "http_settings": {
            "enabled": true,
            "oidc_settings": {
                "enabled": true,
                "service_domain_name": "https://example.bnntest.com",
                "post_auth_redirect_path": "",
                "api_path": ""
            },
            "http_health_check": {
                "enabled": false,
                "method": "",
                "path": "",
                "user_agent": "",
                "from_address": [],
                "https": false
            },
            "exempted_paths": {
                "enabled": false,
                "paths": [],
                "patterns": [
                    {
                        "hosts": [
                            {
                                "origin_header": [],
                                "target": []
                            }
                        ],
                        "methods": [],
                        "mandatory_headers": [],
                        "paths": [],
                        "source_cidrs": []
                    }
                ]
            }
        },
        "client_cidrs": []
    }
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request

Response Headers

N/A

Response Body

If a Service with the name does exist in the cluster, then it is updated.

If a Service with the name doesn’t already exist in the cluster, then a new Service is created and the complete service is returned.

{
   "ServiceID":"example_web_service.release-rc.bnn",
   "ServiceName":"example_web_service",
   "ClusterName":"release-rc",
   "ServiceType":"origin",
   "ServiceDiscovery":"",
   "ServiceVersion":1,
   "Description":"web service     example ",
   "CreatedBy":"devanath+releaseorg@banyansecurity.io",
   "CreatedAt":1607059344852457801,
   "LastUpdatedBy":"devanath+releaseorg@banyansecurity.io",
   "LastUpdatedAt":1607059344852457801,
   "DeletedBy":"",
   "    DeletedAt":0,
   "External":"",
   "OIDCEnabled":"TRUE",
   "OIDCClientSpec":"{\"trust_auth\":\"https://releaseorg.trust-release.bnntest.com/v2/auth\",\"trust_cb\":\"https://example.bnntest.com/bnn_trust_cb\",\"clie    nt_id\":\"_6MVnXGnxZAAYvVGU7PtbA\",\"client_secret\":\"j5n4icRX-pRaDLrvIr8Giw\",\"trust_callbacks\":{},\"disallow_async_auth_redirect\":false}",
   "ServiceSpec":"{    \"kind\": \"BanyanService\",    \"apiVe    rsion\": \"rbac.banyanops.com/v1\",    \"type\": \"origin\",    \"metadata\": {        \"name\": \"example_web_service\",        \"description\": \"web service example \",        \"cluster\": \"release-r    c\",        \"tags\": {            \"template\": \"WEB_USER\",            \"user_facing\": \"true\",            \"protocol\": \"https\",            \"domain\": \"example.bnntest.com\",            \"port\\    ":"\\""443\",            \"icon\": \"cloud\",            \"service_app_type\": \"WEB\"        }    },    \"spec\": {        \"attributes\": {            \"frontend_addresses\": [                {                        \"cidr\": \"\",                    \"port\": \"443\"                }            ],            \"host_tag_selector\": [                {                    \"com.banyanops.hosttag.site_name\":     \"deva-net-mar4\"                }            ],            \"tls_sni\": [                \"example.bnntest.com\"            ]        },        \"backend\": {            \"target\": {                \"na    me\": \"34.70.156.134\",                \"port\": \"433\",                \"tls\": true,                \"tls_insecure\": true,                \"client_certificate\": false            },            \"dns    _overrides\": {},            \"whitelist\": [],            \"http_connect\": false,            \"allow_patterns\": []        },        \"cert_settings\": {            \"dns_names\": [                \"ex    ample.bnntest.com\"            ],            \"custom_tls_cert\": {                \"enabled\": false,                \"cert_file\": \"\",                \"key_file\": \"\"            }        },            \"http_settings\": {            \"enabled\": true,            \"oidc_settings\": {                \"enabled\": true,                \"service_domain_name\": \"https://example.bnntest.com\",                    \"post_auth_redirect_path\": \"\",                \"api_path\": \"\"            },            \"http_health_check\": {                \"enabled\": false,                \"method\": \"\",                    \"path\": \"\",                \"user_agent\": \"\",                \"from_address\": [],                \"https\": false            },            \"exempted_paths\": {                \"enabled\": false    ,                \"paths\": [],                \"patterns\": [                    {                        \"hosts\": [                            {                                \"origin_header\": [],                                    \"target\": []                            }                        ],                        \"methods\": [],                        \"mandatory_headers\": [],                            \"paths\": [],                        \"source_cidrs\": []                    }                ]            }        },        \"client_cidrs\": []    }}",
   "UserFacing":"TRUE",
   "Protocol":"https    ",
   "Domain":"example.bnntest.com",
   "Port":443,
   "Enabled":"TRUE",
   "IsDefault":false
}

Delete a service

HTTP Request

DELETE /delete_registered_service

URL Parameters

N/A

Query Parameters

Parameter Format Description
ServiceID String The ID of the Service 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


Enable a registered service

Enables a registered service and then sends the notification to all Shields of its Organization.

HTTP Request

POST /enable_registered_service?ServiceID=S

URL Parameters

NA

Query Parameters

Parameter Format Description
ServiceID String The ID of the service 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": "Service sample-service.cluster.bnn enabled successfully"
}

Disable a registered service

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

HTTP Request

POST /disable_registered_service?ServiceID=S

URL Parameters

NA

Query Parameters

Parameter Format Description
ServiceID String The ID of the service 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": "Service sample-service.cluster.bnn disabled successfully"
}

Create a service bundle

Creates a new service bundle or add one service to a bundle.

HTTP Requests

POST /experimental/v2/bundle - create a service bundle.

POST /experimental/v2/bundle/<bundle_id>/service - add one service to a bundle.

URL Parameters

N/A

Request Headers

Authorization: $ADMINTOKEN

Request Body

Sample JSON body/bundle:

{
    "bundle_name": "some bundle",
    "description": "some description",
    "service_ids": ["2", "3"],
    "bulk_connect": true
}

Sample JSON body /bundle/ /service - add one service to a bundle

{
    "service_id": "1"
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request
401 Unauthorized
403 Forbidden

Response Headers

N/A

Response Body

{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": {
        "id": "my-bundle-id",
        "bundle_name": "some bundle",
        "description": "some description",
        "is_admin_created": true,
        "bulk_connect": true,
        "created_at": 12345454,
        "updated_at": 12345465,
        "service_ids": ["2", "3"]
    }
}

Update an existing service bundle

Updates an existing service bundle.

HTTP Request

PUT /experimental/v2/bundle/<bundle_id>

URL Parameters

N/A

Request Headers

Authorization: $ADMINTOKEN

Request Body

JSON string

Sample JSON body:

{
    "bundle_name": "new bundle name",
    "description": "new description",
    "service_ids": ["1", "2", "3"],
    "bulk_connect": false
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request
401 Unauthorized
403 Forbidden

Response Headers

N/A

Response Body

{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": {
        "id": "my-bundle-id",
        "bundle_name": "new bundle name",
        "description": "new description",
        "is_admin_created": true,
        "bulk_connect": false,
        "created_at": 12345454,
        "updated_at": 12345465,
        "service_ids": ["1", "2", "3"]
    }
}

Delete a service bundle

Delete an existing service bundle or delete one service from a bundle.

HTTP Request

DELETE /experimental/v2/bundle/<bundle_id> - delete a service bundle

DELETE /experimental/v2/bundle/<bundle_id>/service - remove one service from a bundle

URL Parameters

N/A

Request Headers

Authorization: $ADMINTOKEN

Request Body

JSON string

Sample JSON body /bundle:

{}

Sample JSON body /bundle/ /service - remove one service from a bundle

{
    "service_id": "1"
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request
401 Unauthorized
403 Forbidden

Response Headers

N/A

Response Body

{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": {}
}

Add a service to a bundle

Associate a new service with a bundle.

HTTP Request

POST /experimental/v2/service_bundle

URL Parameters

N/A

Request Headers

Authorization: $ADMINTOKEN

Request Body

JSON string

Sample JSON body:

{
    "bundle_id": "my-bundle-id",
    "service_ids": ["1", "2", "3"]
}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request
401 Unauthorized
403 Forbidden

Response Headers

N/A

Response Body

{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": {
        "bundled_services": [
            {
                "id": "bundled-service-id1",
                "org_id": "org-id",
                "bundle_id": "my-bundle-id",
                "service_id": "1",
                "created_at": 123456,
                "updated_at": 123456
            },
            {
                "id": "bundled-service-id2",
                "org_id": "org-id",
                "bundle_id": "my-bundle-id",
                "service_id": "2",
                "created_at": 123456,
                "updated_at": 123456
            },
            {
                "id": "bundled-service-id3",
                "org_id": "org-id",
                "bundle_id": "my-bundle-id",
                "service_id": "3",
                "created_at": 123456,
                "updated_at": 123456
            }
        ]
    }
}

Remove a service from a bundle

Removes an existing association between a service and a bundle.

HTTP Request

DELETE /experimental/v2/service_bundle/<bundled-service-id>

URL Parameters

N/A

Request Headers

Authorization: $ADMINTOKEN

Request Body

JSON string

Sample JSON body:

{}

Status Codes and Errors

Value Description
200 OK
500 Internal Server Error
400 Bad Request
401 Unauthorized
403 Forbidden

Response Headers

N/A

Response Body

{
    "request_id": "",
    "error_code": 0,
    "error_description": "",
    "data": {}
}

Last modified: Jul 08, 2021