Merge pull request #1988 from EnterpriseDB/release/2021-11-02

Release/2021 11 02
EnterpriseDB · Nov 2, 2021 · 6937f4c · 6937f4c
2 parents 9198a51 + 13d3838
commit 6937f4c
Show file tree

Hide file tree

Showing 5 changed files with 585 additions and 409 deletions.
diff --git a/build-sources.json b/build-sources.json
@@ -23,5 +23,5 @@
   "postgis": true,
   "repmgr": true,
   "slony": true,
-  "edbcloud": true
+  "biganimal": true
 }
diff --git a/product_docs/docs/biganimal/release/reference/api.mdx b/product_docs/docs/biganimal/release/reference/api.mdx
@@ -0,0 +1,331 @@
+---
+title: 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](https://portal.biganimal.com). The direct documentation link is [https://portal.biganimal.com/api/docs/](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](#query-the-authentication-endpoint).
+2. [Request the device code](#request-the-device-code-using-curl).
+3. [Authorize as a user](#authorize-as-a-user).
+4. [Request the raw token](#request-the-raw-token-using-curl).
+5. [Exchange for the raw token for the BigAnimal token](#exchange-the-biganimal-token-using-curl).
+
+
+EDB provides an optional script to simplify getting your device code and getting and refreshing your tokens. See [Using the `get-token` script](#using-the-get-token-script) for details.
+
+
+## Query the authentication endpoint
+
+This call returns the information that either:
+
+- you need later if you are using `curl` to request the device code and tokens, or
+- the `get-token` script uses to generate the tokens for you
+
+
+```
+curl https://portal.biganimal.com/api/v1/auth/provider
+```
+
+The response returns the `clientId`, `issuerUri`, `scope`, and `audience`. For example:
+```
+{
+  "clientId": "pM8PRguGtW9yVnrsvrvpaPyyeS9fVvFh",
+  "issuerUri": "https://auth.biganimal.com",
+  "scope": "openid profile email offline_access",
+  "audience": "https://portal.biganimal.com/api"
+}
+```
+
+EDB recommends you store the output in environment variables to make including them in the following calls easier. For example:
+
+```
+CLIENT_ID=pM8PRguGtW9yVnrsvrvpaPyyeS9fVvFh
+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`
+!!!note
+   The `get-token` script executes this step. You don't need to make this call if you are using the script.
+!!!
+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](#request-the-token-using-curl).
+- `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](#authorize-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` indicates the lifetime (in seconds) of the `device_code` and `user_code`.
+- `interval` indicates the interval (in seconds) at which the app should poll 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
+
+To authorize as a user:
+
+1. Go to the `verification_uri` in your web browser, enter your `user_code`, and select **Continue**.
+
+2. Select **Confirm** on the Device Confirmation dialog.
+
+3. Select **Continue with Microsoft Azure AD** on the BigAnimal Welcome screen.
+
+4. Log in with your Azure AD credentials.
+
+
+## Request the raw token using `curl`
+!!!note
+   The `get-token` script executes this step. You don't need to make this call if you are using the script. See [Request your token using `get-token`](#request-your-token-using-get-token).
+!!!
+
+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 has expired. (See [Refresh tokens](https://auth0.com/docs/tokens/refresh-tokens) for more information.) Refresh tokens expire after 30 days.
+
+- `expires_in` - means the token expires after 24 hours since 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"
+```
+
+!!!note
+The access token obtained at this step is only used in the next step to exchange the BigAnimal token.
+!!!
+
+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](#request-the-device-code-using-curl).
+
+- `slow_down` - slow down and use the suggested interval retrieved when you [requested the device code](#request-the-device-code-using-curl). To avoid receiving this error due to network latency, you should start counting each interval after receipt of the last polling request's response.
+- `expired_token` - you have not authorized the device quickly enough, so the `device_code` has expired. Your application should notify you that it has expired and to restore it.
+- `access_denied`
+
+## Exchange the BigAnimal token using `curl`
+!!!note
+   The `get-token` script executes this step. You don't need to make this call if you are using the script.
+!!!
+
+Use the raw token you obtained in the previous step [Request the raw token using `curl`](#request-the-raw-token-using-curl) to get the BigAnimal token:
+
+```
+curl -s --request POST \
+     --url "https://portal.biganimal.com/api/v1/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"
+```
+
+!!! Tip
+Contact [Customer Support](../overview/06_support) if you have trouble obtaining a valid access token to access BigAnimal API.
+!!!
+
+## Calling 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/v1/postgres-types" \
+  --header "authorization: Bearer $ACCESS_TOKEN"  \
+  --header "content-type: application/json"
+```
+
+Example response:
+```
+{
+  "pgTypesList": [
+    {
+      "id": "epas",
+      "name": "EDB Postgres Advanced Server",
+      "description": "",
+      "dockerImage": ""
+    },
+    {
+      "id": "postgres",
+      "name": "PostgreSQL",
+      "description": "",
+      "dockerImage": ""
+    }
+  ]
+}
+```
+
+
+## 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. You shouldn't call the endpoint to get a new access token every time you call an API. There are rate limits that throttle the amount of requests to the endpoint that can be executed using the same token from the same IP.
+
+### Refresh your t.oken Using `curl`
+!!!note
+The `get-token` script has an option to execute this step. See [Refresh the token using `get-token`](#refresh-the-token-using-get-token).
+!!!
+
+If you are not 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](#request-the-device-code).
+
+The `client_id` is always the same one in the response when you [queried the authentication endpoint](#query-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 an BigAnimal token. See [Exchange for BigAnimal token](#exchange-the-biganimal-token-using-curl) for more information.
+
+!!! Note
+    You need to save the refresh token retrieved from this response for the next refresh call. The refresh token in the response when you originally [requested the token](#request-the-token) is obsoleted once it has been used.
+
+
+
+## Using the `get-token` script
+
+
+To simplify the process of getting tokens, EDB provides the `get-token` script. You can download it [here](https://github.com/EnterpriseDB/cloud-utilities/tree/main/api).
+
+To use the script, install the [jq command-line JSON processor](https://stedolan.github.io/jq/) specific to your OS.
+
+Before running the script, [query the authentication endpoint](#query-the-authentication-endpoint).
+
+### get-token usage
+
+```
+Get Tokens for BigAnimal API
+
+Usage:
+  ./get-token.sh [flags] [options]
+
+      -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/
+```
+
+### 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": "xxxxxxxxxx",
+  "refresh_token": "xxxxxxxxxxxx",
+  "scope": "openid profile email offline_access",
+  "expires_in": 86400,
+  "token_type": "Bearer"
+}
+```
+