From 14e5f47d9e72af5213ac9998ee5c0a4c5d12bdc5 Mon Sep 17 00:00:00 2001
From: Austin Valeske <avaleske@google.com>
Date: Fri, 5 May 2023 22:23:07 -0400
Subject: [PATCH] Add initial pass at 'getting started' checklist

---
 docs/SUMMARY.md                       |  3 +-
 docs/it-manual/api/getting-started.md | 55 +++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 docs/it-manual/api/getting-started.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 6aaef8dc..c534d4af 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -75,6 +75,7 @@
 * [Infrastructure Requirements](it-manual/infrastructure-requirements.md)
 * [Existing deployments](it-manual/existing-deployments.md)
 * [API Integration](it-manual/api/README.md)
+  * [Getting Started](it-manual/api/getting-started.md)
   * [Authentication](it-manual/api/authentication.md)
   * [List applications](it-manual/api/program-applications.md)
   * [API specification](it-manual/api/api-specification.md)
@@ -98,7 +99,7 @@
     * [Backend data model](contributor-guide/developer-guide/system-design/backend-data-model.md)
     * [Data Versioning model](contributor-guide/developer-guide/system-design/data-versioning-model.md)
   * [Database](contributor-guide/developer-guide/database/README.md)
-    * [DB Schema](contributor-guide/developer-guide/database/db-schema.md) 
+    * [DB Schema](contributor-guide/developer-guide/database/db-schema.md)
     * [Data dictionary](contributor-guide/developer-guide/database/data-dictionary.md)
     * [Cookbook](contributor-guide/developer-guide/database/sql-cookbook.md)
   * [File storage backend](contributor-guide/developer-guide/file-storage-backend.md)
diff --git a/docs/it-manual/api/getting-started.md b/docs/it-manual/api/getting-started.md
new file mode 100644
index 00000000..6fbd57e1
--- /dev/null
+++ b/docs/it-manual/api/getting-started.md
@@ -0,0 +1,55 @@
+# Getting Started
+
+To get started using the API, we can connect from either our personal machine or another service. Connecting from your personal machine will usually
+
+
+## Connect from your personal machine
+
+1. To connect to the CiviForm API, you'll first need to determine your IP address.
+1. If you're connecting to CiviForm across the public internet (for example, if CiviForm is hosted on AWS) you can use the following curl command:\
+    {% code %}
+    ```shell
+      curl ifconfig.me
+    ```
+    {% endcode %}
+
+1. In the CiviForm Admin, click "API keys" and then "New API Key"
+1. Fill out the "Create a new API key" form, providing the IP address determined in Step 2, and selecting the program names you'll want to access with this key, and click Save. _Since we're only using this key for testing, set it to expire in a few days._
+
+    {% hint style="info" %}
+    When you provide your IP address, add `/32` to the end. If your IP address was `55.55.55.55`, you'd type `55.55.55.55/32` into the form.
+    {% endhint %}
+
+1. The next page will show your API key. *This is your only chance to see the key, it can not be retrieved later.* Copy it somewhere secure for the next step.
+1. To test your API key and your connection to CiviForm, use the following curl command and replace `[Your CiviForm URL]` and `[Your API Key]` with the URL of your CiviForm instance and your API key, respectively:\
+    {% code overflow="wrap" %}
+    ```shell
+      curl [Your CiviForm URL]/api/v1/checkAuth -H "Authorization: Basic [Your API Key]" -H "Content-Type: application/json" -v
+    ```
+    {% endcode %}
+
+{% hint style="info" %}
+If you see an `HTTP/2 200` in the output then you've succeeded!
+{% endhint %}
+
+{% hint style="warning" %}
+If you see an `HTTP/2 401` in the output then something is wrong. You may have used the wrong IP address, typo'd the API key, or some other issue.
+{% endhint %}
+
+Also note: If you move locations or restart your computer, your IP address may change, and you'll need to generate a new API key.
+
+to put somewhere:
+If you're connecting to an on-prem instance of CiviForm, determing the IP address that CiviForm will see your traffic originating from can be more difficult, and you should check with your IT administrator.
+
+## Connect from another service
+Connecting to CiviForm from another service, such as IBM Cloud Pak for Data or Microsoft Dynamics CRM, you can follow similar steps as above.
+
+The primary difference is that you'll need to know the IP addresses that service will be connecting from.
+
+Cloudpak for data:
+https://dataplatform.cloud.ibm.com/docs/content/wsj/admin/firewall_cfg.html
+
+Microsoft Dynamics Cloud:
+https://learn.microsoft.com/en-us/power-platform/admin/online-requirements#ip-addresses-required
+
+but it seems like microsoft might change the IP address ranges?