Introduction to the Banyan Command Center API

Authenticate and configure Banyan via the API interface

Banyan Command Center API Endpoint

The Banyan Command Center API endpoint is typically at: https://net.banyanops.com/api/v1

If your organization is provisioned on a different Command Center, you should use specific domain of your Command Center.


API Authentication

The Banyan API uses HTTP Bearer token authentication. You have to follow a two-step process to obtain an Access Token that allows you to access an API:

  1. Generate a personal Refresh Token via the “My Profile” page on the Banyan Cloud Command Center
  2. Use the Refresh Token to authorize yourself and receive an Access Token

Authentication Step 1 - Generate Personal Refresh Token

SAML Admins log in via Single Sign-On and cannot generate a Refresh Token. You must be logged into the Banyan Command Center as a Local Banyan Admin in order to generate a Refresh Token. If you are a SAML Admin, please have your account Owner create a Local Admin account using a unique email address, and use that Local Admin account before proceeding to the steps below.

To generate a personal Refresh Token:

  1. Log in to your instance of the Banyan Command Center.

  2. Navigate to the My Profile page, and then click Generate Token.

Authentication Step 2 - Receive an Access Token

One you have the Refresh Token, use it to receive an Access Token.

POST /refresh_token
Authorization: Bearer eyJhb...YOUR_REFRESH_TOKEN

{
  "Message": "eyJhb...YOUR_ACCESS_TOKEN"
}

The equivalent Curl command is:

curl -X POST --header "Authorization: Bearer eyJhb...YOUR_REFRESH_TOKEN" $API_ENDPOINT/refresh_token

{
  "Message":"eyJhb...YOUR_ACCESS_TOKEN"
}

Using the API

Once you have your Access Token, you can use it as your Bearer token via the HTTP header Authorization: Bearer eyJhb...YOUR_ACCESS_TOKEN to access to the Banyan API.

For example, to access the Banyan Events API, the HTTP request would look like:

GET /events
Authorization: Bearer eyJhb...YOUR_ACCESS_TOKEN

The equivalent Curl command is:

curl --header "Authorization: Bearer eyJhb...YOUR_ACCESS_TOKEN" $API_ENDPOINT/events

Python Library and CLI

pybanyan is a Python API client and Command Line Interface (CLI) tool. You can use the commands and subcommands in pybanyan to interact with the Banyan API.

$ banyan
usage: banyan [options] <command> <subcommand> [<subcommand> ...] [parameters]

API library and command-line interface for Banyan Security

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug           full application debug mode
  -q, --quiet           suppress all console output
  -v, --version         show program's version number and exit
  --api-url API_URL     URL for the Banyan API server. Can also be configured
                        via the BANYAN_API_URL environment variable.
  --refresh-token REFRESH_TOKEN
                        API token used for the initial authentication to the
                        Banyan API server. Can also be configured via the
                        BANYAN_REFRESH_TOKEN environment variable.
  --output-format {table,json,yaml}, -o {table,json,yaml}
                        desired output format (table, json, yaml)

Commands:
  {event,admin,device,user,netagent,shield,policy,role,service}
    event               report on security and audit events
    admin               manage administrator accounts
    device              manage devices
    user                manage user accounts
    netagent            manage netagents (AccessTiers and HostAgents)
    shield              manage Banyan Shield clusters
    policy              manage authorization policies for users and workloads
    role                manage user and workload roles
    service             manage web and TCP services and workloads

Managing the Refresh Token and Access Token

The Refresh Token, and generated Access Tokens, gives you full API access to your account. Please store these tokens securely and do not provide them to a third party.

The Controller provides one Refresh Token per user account. The Refresh Token never expires but you can revoke the Refresh Token at any time via the Banyan Command Center Web Console.

To revoke a Refresh Token:

  1. Log in to your instance of the Banyan Cloud Command Center.

  2. Navigate to the My Profile page, and then click Revoke Token.

  1. Click Continue in the warning popup windowhg.
Last modified: Jul 22, 2021