Authentication

General Authentication

All Banyan APIs utilize the same mechanism for authenticating against the services. Please use the API reference to test out your keys and interact with the API's authentication.

Contact your Banyan representative to obtain an API "Client ID" and "Client Secret" to be used on the authorization end point. Once you have your ID and secret, you will use your preferred means of making REST API calls. We use curl below for general demonstration of the API. We also use the command line tool jq to extract elements of the JSON data received. We use the tool base64 to encode our key and secret for transmission.

For convenience, let's save the API secret and key you obtained from your Banyan representative as shell variables:

CLIENT_ID='<your client ID here>'
CLIENT_SECRET='<the provided secret for your client ID here>'

With these, we can obtain a token. We'll use curl to make the call and jq to extract the access token, while save the result to another shell variable which we can then reuse.

TOKEN=$(curl --silent -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Grant_Type: client_credentials" \
--data "client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}" \
"https://api.banyan.com/oauth/token" | \
jq -r .access_token)

⚠️

Do not paste example code from a word processor!

See the Example Usage section for how to best edit commands for use in the shell.

Tokens expire every 60 minutes. Attempting to use an expired token will result in a 401 error response; when this happens, simply make another call to /oauth/token to obtain a new one.

To confirm that you have obtained a valid token, you can make a call like the following:

curl -s -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.banyan.com/rest/v1/version" | \
jq .

You should see a JSON result with version metadata about the service's most recent deployment.