Using the BigAnimal API

Use the BigAnimal API to integrate directly with BigAnimal for management activities such as cluster provisioning, de-provisioning, and scaling.

The API reference documentation is available from the BigAnimal portal. The direct documentation link is https://portal.biganimal.com/api/docs/.

To access the API, you need a token. The high-level steps to obtain a token are:

1. Query the authentication endpoint.
2. Request the device code.
3. Authorize as a user.
4. Request the raw token.
5. Exchange for the raw token for the BigAnimal token.

EDB provides an optional script to simplify getting your device code and getting and refreshing your tokens. See Using the get-token script for details.

Query the authentication endpoint

This call returns the information that either:

• You need later if you're using curl to request the device code and tokens.
• The get-token script uses to generate the tokens for you.

curl https://portal.biganimal.com/api/v3/auth/provider

The response returns the clientId, freetrialClientId, issuerUri, scope, and audience. For example:

{
  "clientId": "5B79FAjzKF2Ig5dVFAOhc1acDSJYY2xh",
  "freetrialClientId": "m71bEVZrGsWiKtPqMI3hYCHCG3EYLPDk",
  "issuerUri": "https://auth.biganimal.com",
  "scope": "openid profile email offline_access",
  "audience": "https://portal.biganimal.com/api"
}

EDB recommends that you store the output in environment variables so that including them in the following calls is easier. For example:

CLIENT_ID=5B79FAjzKF2Ig5dVFAOhc1acDSJYY2xh
ISSUER_URL=https://auth.biganimal.com
SCOPE="openid profile email offline_access"
AUDIENCE="https://portal.biganimal.com/api"

The following example calls use these environment variables.

Request the device code using curl

This call gets a device code:

curl --request POST \
  --url "$ISSUER_URL/oauth/device/code" \
  --header "content-type: application/x-www-form-urlencoded" \
  --data "client_id=$CLIENT_ID" \
  --data "scope=$SCOPE" \
  --data "audience=$AUDIENCE"

The response returns:

• device_code — The unique code for the device. When you go to the verification_uri in your browser-based device, this code is bound to your session. You use this code in your request for a token.
• user_code — The code you input at the verification_uri to authorize the device. You use this code when you authorize yourself as a user.
• verification_uri — The URL you use to authorize your device.
• verification_uri_complete — The complete URL you use to authorize the device. You can use this URL to embed the user code in your app's URL.
• expires_in — The lifetime (in seconds) of the device_code and user_code.
• interval — The interval (in seconds) at which the app polls the token URL to request a token.

For example:

{
  "device_code": "KEOY2_5YjuVsRuIrrR-aq5gs",
  "user_code": "HHHJ-MMSZ",
  "verification_uri": "https://auth.biganimal.com/activate",
  "expires_in": 900,
  "interval": 5,
  "verification_uri_complete": "https://auth.biganimal.com/activate?user_code=HHHJ-MMSZ"
}

Store the device code in an environment variable for future use. For example:

DEVICE_CODE=KEOY2_5YjuVsRuIrrR-aq5gs

Authorize as a user

1. Go to the verification_uri in your web browser, enter your user_code, and select Continue.

2. On the Device Confirmation dialog, select Confirm.

3. On the BigAnimal Welcome screen, select Confirm.

Request the raw token using curl

The curl --request POST call requests a token. For example:

curl --request POST \
  --url "$ISSUER_URL/oauth/token" \
  --header "content-type: application/x-www-form-urlencoded" \
  --data "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  --data "device_code=$DEVICE_CODE" \
  --data "client_id=$CLIENT_ID"

If successful, the call returns:

• access_token — Use to exchange for the token to access BigAnimal API.

• refresh_token — Use to obtain a new access token or ID token after the previous one expires. (See Refresh tokens for more information.) Refresh tokens expire after 30 days.

• expires_in — Means the token expires after 24 hours from its creation.

For example:

{
  "access_token": "eyJhbGc.......1Qtkaw2fyho",
  "id_token": "eyJhbGci.......FBra7tA",
  "refresh_token": "v1.MTvuZpu.......sbiionEhtTw",
  "scope": "openid profile email offline_access",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Store the access token and refresh token in environment variables for future use. For example:

RAW_ACCESS_TOKEN="eyJhbGc.......1Qtkaw2fyho"
REFRESH_TOKEN="v1.MTvuZpu.......sbiionEhtTw"

If not successful, you receive one of the following errors:

• authorization_pending — Continue polling using the suggested interval retrieved when you requested the device code.

• slow_down — Slow down and use the suggested interval retrieved when you requested the device code. To avoid receiving this error due to network latency, start counting each interval after receipt of the last polling request's response.

• expired_token — You didn't authorize the device quickly enough, so the device_code expired. Your application notifies you that it has expired and to restore it.

• access_denied

Exchange the BigAnimal token using curl

Use the raw token you obtained in the previous step Request the raw token using curl to get the BigAnimal token:

curl -s --request POST \
     --url "https://portal.biganimal.com/api/v3/auth/token" \
     --header "content-type: application/json" \
     --data "{\"token\":\"$RAW_ACCESS_TOKEN\"}"

If successful, the call returns:

• token — The bearer token used to access the BigAnimal API.

For example:

{
  "token": "eyJhbGc.......0HFkr_19Vr7w"
}

This token, as opposed to the raw-access token, is recognized by the BigAnimal API. Store this token in environment variables for future use. For example:

ACCESS_TOKEN="eyJhbGc.......0HFkr_19Vr7w"

Call the API

To call the BigAnimal API, your application must pass the retrieved access token as a bearer token in the Authorization header of your HTTP request. For example:

curl --request GET \
  --url "$AUDIENCE/v3/projects" \
  --header "authorization: Bearer $ACCESS_TOKEN"  \
  --header "content-type: application/json"

Example response:

{
    "projectId": "prj_abcd1234",
    "projectName": "Test project",
    "clusterCount": 4,
    "userCount": 10,
    "cloudProviders": [
    {
       "cloudProviderId": "aws",
       "cloudProviderName": "AWS"
    },
    {
       "cloudProviderId": "azure",
       "cloudProviderName": "Azure"
    }
  ]
}

Refresh your token

You use the refresh token to get a new raw-access token. Usually you need a new access token only after the previous one expires or when gaining access to a new resource for the first time. Don't call the endpoint to get a new access token every time you call an API. Rate limits can throttle the amount of requests to the endpoint that can be executed using the same token from the same IP.

Refresh your token using curl

If you aren't using the get-token script to refresh your token, make a POST request to the /oauth/token endpoint in the Authentication API, using grant_type=refresh_token. For example:

curl --request POST \
  --url "$ISSUER_URL/oauth/token" \
  --header "content-type: application/x-www-form-urlencoded" \
  --data "grant_type=refresh_token" \
  --data "client_id=$CLIENT_ID" \
  --data "refresh_token=$REFRESH_TOKEN"

The refresh_token is in the response when you requested the token.

The client_id is always the same one in the response when you queried the authentication endpoint.

The response of this API call includes the access_token. For example:

{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "refresh_token": "v1.Mjv..._2pRs",
  "token_type": "Bearer"
}

Store the access token and refresh token in environment variables for future use. For example:

RAW_ACCESS_TOKEN="eyJhbGc.......1Qtkaw2fyho"
REFRESH_TOKEN="v1.MTvuZpu.......sbiionEhtTw"

The token you obtain from this step is the raw-access token. You need to exchange this token for a BigAnimal token. See Exchange for BigAnimal token for more information.

Using the get-token script

To simplify the process of getting tokens, EDB provides the get-token script. You can download it here.

To use the script, install the jq command-line JSON processor specific to your OS.

Before running the script, query the authentication endpoint.

get-token usage

Get Tokens for BigAnimal API

Usage:
  ./get-token.sh [flags] [options]

      -ft, --freetrial                   [optional] login with BigAnimal free trial account
      -o,  --format  json | plain        [optional] output format, default 'json'
      -r,  --refresh <refresh_token>     [optional] query for tokens again by the given refresh_token
                                           this revokes and rotates the given refresh token,
                                           please remember the newly returned refresh_token for
                                           the next use
      -h,  --help                         show this help message

Reference: https://www.enterprisedb.com/docs/biganimal/latest/reference/api/

Request your token using get-token

To use the get-token script to get your tokens, use the script without the --refresh option. For example:

./get-token.sh -o plain

Please login to
https://biganimal.us.auth0.com/activate?user_code=ZMNX-VVJT
with your BigAnimal account
Have you finished the login successfully? (y/N) y

####### Access Token ################
eyxxxxxxxxxxxxxx

####### Refresh Token ###############
xxxxxxxxxx

#####   Expires In Seconds ##########
86400

Refresh the token using get-token

To use the get-token script to refresh your token, use the script with the --refresh <refresh_token> option. For example:

./get-token.sh -o json --refresh v1.MVZ9_xxxxxxxx_FRs

{
  "access_token": "eyJhbGc.......1Qtkaw2fyho",
  "refresh_token": "v1.MVZ9_xxxxxxxx_FRs",
  "scope": "openid profile email offline_access",
  "expires_in": 86400,
  "token_type": "Bearer"
}

• On this page
• Query the authentication endpoint
• Request the device code using curl
• Authorize as a user
• Request the raw token using curl
• Exchange the BigAnimal token using curl
• Call the API
• Refresh your token
• Using the get-token script