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 secret and key to be used on the authorization end point. Once you have your key and ID, 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:

API_SECRET=<long string data>
API_KEY=<slightly shorter string data>

We need to prepare these key and secrets to be used in our http call. To do so we format them properly and base 64 encode them:

ENCODED=$(echo "$API_KEY:$API_SECRET" | base64)

Now 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 "Authorization: Basic $ENCODED" \
"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 30 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 -v -s -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.banyan.com/rest/v1/version"

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