diff --git a/docs/integration/sql-account-api/_category_.json b/docs/integration/sql-account-api/_category_.json new file mode 100644 index 00000000..667f8d4e --- /dev/null +++ b/docs/integration/sql-account-api/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "SQL Account API", + "position": 2, + "link": { + "type": "generated-index", + "description": "A quick guide on SQL Account API" + } +} \ No newline at end of file diff --git a/docs/integration/sql-account-api/api-on-premise-setup.md b/docs/integration/sql-account-api/api-on-premise-setup.md new file mode 100644 index 00000000..25b0f393 --- /dev/null +++ b/docs/integration/sql-account-api/api-on-premise-setup.md @@ -0,0 +1,92 @@ +--- +sidebar_position: 1 +id: on-premise-setup +title: On-Premise Setup +description: A guide to setup sql mobile connect on-premise +slug: /sql-account-api/on-premise-setup +tags: ["SQL Account", "SQL Account API", "On-Premise Setup"] +--- + +## Prerequisites + +- `SQL Account` **version 5.2025.1038.875** or above +- Fix server IP address (either DHCP Reservation or Static) +- [Public IP Address](#public-ip-address) +- [Port Forwarding](#step-3---port-forwarding) + +## Public IP Address + +Make sure to have a **dedicated public IP Address**. + +:::info[Check Public IP Address] +You can using [SQL Connect Detector](https://connect.sql.com.my/document/private-cloud/requirements/sql-connect-detector#download) to check whether public IP is enabled by your ISP. + +Make sure the last requirement **Port Forward?** is in **Green** +::: + +:::tip[Hints] +If the result is **Red**, kindly call your internet service provider and request for dedicated Public IP. + +If the provider requests a reason, you can explain that you intend to host a server and therefore need to set up port forwarding. +::: + +## Setup + +### Step 1 - Install SQL API Service + +1. On `Logon Screen` > **Click** `⚙️` + + ![logon screen setting](../../../static/img/sql-account-api/on-premise-setup/1.png) + +2. **Right-Click** on company database > **Select** `Configure API Service...` + + ![configure mobile connect](../../../static/img/sql-account-api/on-premise-setup/2.png) + +3. **Click** on `Install` to install API service + + ![install mobile connect](../../../static/img/sql-account-api/on-premise-setup/3.png) + +### Step 2 - Start Service + +After the installation, start the service. Once successful, `Service is running` status will show on screen. + +![service running](../../../static/img/sql-account-api/on-premise-setup/4.png) + +### Step 3 - Port Forwarding + +Next, we will need to do `Port Forwarding`. + +:::info[Port Forwarding Information] +You can **Click** on `Show Tips` to find all the information for port forwarding configuration. + +![show tips](../../../static/img/sql-account-api/on-premise-setup/5.png) +::: + +1. **Access Router Setting**: Login to the router's administration interface on web browser. + + You can **Click** on `Show Tips` > `Gateway IP Address`, to access login page of the router. + + :::warning + If you are using a firewall or serving the router's web administration interface via a different IP address, this might not work. + ::: + + ![router gateway](../../../static/img/sql-account-api/on-premise-setup/6.png) + +2. **Navigate to Port Forwarding Section**: Find `Port Forwarding`, `Virtual Service` or similar section in the router's setting. + +3. **Add New Rule**: Create a new port forwarding rule. (All information can get from [Port Forwarding Information](#step-3---port-forwarding)) + + - `Service Name`: Enter a description name (**SQL Account API Service**) + - `External/Public Port`: Specify the port number to use for external access (**443**) + - `Internal IP Address`: Enter the IP address of the device to forward to (**E.g. 192.168.0.238**) + - `Internal/Private Port`: Specify the port number the service is listening on within the internal network (**443**) + +4. **Save the Rule**: Save the new port forwarding rule. + +5. **Verify**: **Click** on `Test Connection` to test `SQL Account API Service` status. When `✅ OK` status is shown, it means the service is setup successfully. + + ![alt text](../../../static/img/sql-account-api/on-premise-setup/7.png) + +### Examples of Port Forward + +Can refer to [Sample of port forward setup](../sql-mobile-connect/on-premise-setup#examples-of-port-forward) on different router \ No newline at end of file diff --git a/docs/integration/sql-account-api/generate-api-secret-key.md b/docs/integration/sql-account-api/generate-api-secret-key.md new file mode 100644 index 00000000..84ec7c57 --- /dev/null +++ b/docs/integration/sql-account-api/generate-api-secret-key.md @@ -0,0 +1,78 @@ +--- +sidebar_position: 2 +id: generate-api-secret-key +title: Generate API Secret Key +description: A guide to generate SQL Account API secret key +slug: /sql-account-api/generate-api-secret-key +tags: ["SQL Account", "SQL Account API", "Generate API Secret Key"] +--- + +This guide will walk through generating `API Secret Key`, which allow the user to access SQL Account API Services. + +## Step to Generate API Secret Key + +1. **Navigate to User Detail:** + + Go to `Tools` > `Maintain User...` > `Detail` + +2. **Select API Secret Key Option:** + + **Click** on `More` > `API Secret Key` + + ![1](../../../static/img/sql-account-api/generate-api-secret-key/1.png) + +3. **Generate Secret Key:** + + **Click** on `Generate API Secret Key` + + ![2](../../../static/img/sql-account-api/generate-api-secret-key/2.png) + + :::warning[Important Note] + Once an `API Secret Key` is generated for a user, that user will no longer be able to login on SQL Account directly. The user only be able to access `SQL Account API Service` with the secret key generated. + ::: + +4. **Copy and Save Secret Key** + + The API `Access Key` and `Secret Key` will displayed. Make sure to copy and save it immediately in a secure location. + + ![3](../../../static/img/sql-account-api/generate-api-secret-key/3.png) + + :::info[Tip] + **API Secret Key** can only be retrieved at the time of generated. If you lose it, you can `revoke` and `generate` a new API Secret Key. + ::: + +## Test AWSv4 Signature with API Secret Key + +`SQL Account API Service` uses [AWS Signature Version 4](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html) for authenticating requests. You can **click** on `Test Connection` to test on the request with AWSv4 authorization header. + +![4](../../../static/img/sql-account-api/generate-api-secret-key/4.png) + +:::info[Hints] +For a sample cURL request with AWSv4 authorization header, **click** on `Copy`. +::: + +## Download and Import SQL Account API Postman Collection + +1. **Download Postman Collection:** + + **Click** on `Download Postman Collection` to save `postman_collection.json` file. + + ![5](../../../static/img/sql-account-api/generate-api-secret-key/5.png) + +2. **Import the API specification into your Postman application:** + + **Click** on `Import`, then select `postman_collection.json` file you downloaded to import. + + ![postman-1](../../../static/img/sql-account-api/generate-api-secret-key/postman-1.png) + +3. **Update Access Key and Secret Key:** + + After postman collection imported, **navigate** to `Variables` tab. Then, **replace** the `your_access_key` and `your_secret Key` with the Access Key and Secret Key generated earlier. + + ![postman-2](../../../static/img/sql-account-api/generate-api-secret-key/postman-2.png) + +4. **Test on API Endpoint** + + **Select** on `Agent` endpoint. Then, **click** on `Send` to try retrieve agent data from `SQL Account API Service` and the `Agent` json data list will show on response body. + + ![postman-3](../../../static/img/sql-account-api/generate-api-secret-key/postman-3.png) diff --git a/static/img/sql-account-api/generate-api-secret-key/1.png b/static/img/sql-account-api/generate-api-secret-key/1.png new file mode 100644 index 00000000..839739e0 Binary files /dev/null and b/static/img/sql-account-api/generate-api-secret-key/1.png differ diff --git a/static/img/sql-account-api/generate-api-secret-key/2.png b/static/img/sql-account-api/generate-api-secret-key/2.png new file mode 100644 index 00000000..a5ed557f Binary files /dev/null and b/static/img/sql-account-api/generate-api-secret-key/2.png differ diff --git a/static/img/sql-account-api/generate-api-secret-key/3.png b/static/img/sql-account-api/generate-api-secret-key/3.png new file mode 100644 index 00000000..b6da717d Binary files /dev/null and b/static/img/sql-account-api/generate-api-secret-key/3.png differ diff --git a/static/img/sql-account-api/generate-api-secret-key/4.png b/static/img/sql-account-api/generate-api-secret-key/4.png new file mode 100644 index 00000000..708807fa Binary files /dev/null and b/static/img/sql-account-api/generate-api-secret-key/4.png differ diff --git a/static/img/sql-account-api/generate-api-secret-key/5.png b/static/img/sql-account-api/generate-api-secret-key/5.png new file mode 100644 index 00000000..d8891a70 Binary files /dev/null and b/static/img/sql-account-api/generate-api-secret-key/5.png differ diff --git a/static/img/sql-account-api/generate-api-secret-key/postman-1.png b/static/img/sql-account-api/generate-api-secret-key/postman-1.png new file mode 100644 index 00000000..3ea26e5a Binary files /dev/null and b/static/img/sql-account-api/generate-api-secret-key/postman-1.png differ diff --git a/static/img/sql-account-api/generate-api-secret-key/postman-2.png b/static/img/sql-account-api/generate-api-secret-key/postman-2.png new file mode 100644 index 00000000..ecb212b6 Binary files /dev/null and b/static/img/sql-account-api/generate-api-secret-key/postman-2.png differ diff --git a/static/img/sql-account-api/generate-api-secret-key/postman-3.png b/static/img/sql-account-api/generate-api-secret-key/postman-3.png new file mode 100644 index 00000000..5c739901 Binary files /dev/null and b/static/img/sql-account-api/generate-api-secret-key/postman-3.png differ diff --git a/static/img/sql-account-api/on-premise-setup/1.png b/static/img/sql-account-api/on-premise-setup/1.png new file mode 100644 index 00000000..90aa33a3 Binary files /dev/null and b/static/img/sql-account-api/on-premise-setup/1.png differ diff --git a/static/img/sql-account-api/on-premise-setup/2.png b/static/img/sql-account-api/on-premise-setup/2.png new file mode 100644 index 00000000..64f6a477 Binary files /dev/null and b/static/img/sql-account-api/on-premise-setup/2.png differ diff --git a/static/img/sql-account-api/on-premise-setup/3.png b/static/img/sql-account-api/on-premise-setup/3.png new file mode 100644 index 00000000..aab4e392 Binary files /dev/null and b/static/img/sql-account-api/on-premise-setup/3.png differ diff --git a/static/img/sql-account-api/on-premise-setup/4.png b/static/img/sql-account-api/on-premise-setup/4.png new file mode 100644 index 00000000..4f666904 Binary files /dev/null and b/static/img/sql-account-api/on-premise-setup/4.png differ diff --git a/static/img/sql-account-api/on-premise-setup/5.png b/static/img/sql-account-api/on-premise-setup/5.png new file mode 100644 index 00000000..3e4adb2d Binary files /dev/null and b/static/img/sql-account-api/on-premise-setup/5.png differ diff --git a/static/img/sql-account-api/on-premise-setup/6.png b/static/img/sql-account-api/on-premise-setup/6.png new file mode 100644 index 00000000..7b0960ea Binary files /dev/null and b/static/img/sql-account-api/on-premise-setup/6.png differ diff --git a/static/img/sql-account-api/on-premise-setup/7.png b/static/img/sql-account-api/on-premise-setup/7.png new file mode 100644 index 00000000..38d1e7b5 Binary files /dev/null and b/static/img/sql-account-api/on-premise-setup/7.png differ