Authentication

General Authentication

All Banyan APIs utilize the same mechanism for authenticating against the services. All API guides reference this section for their authentication step.

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.

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>

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 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=${API_KEY}&client_secret=${API_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 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.