Created Store External OAuth2 Token API (markdown)

Store-External-OAuth2-Token-API.md

@@ -0,0 +1,102 @@
+# Store External OAuth2 Token API
+
+Bichon provides an endpoint that allows external systems to supply
+OAuth2 tokens for a specific account. This is useful when OAuth2
+authentication is handled outside Bichon, or when you want Bichon to
+manage token refreshing automatically.
+
+Bichon also includes built-in interactive API documentation page:\
+**http://localhost:15630/api-docs/redoc#tag/OAuth2/operation/store_external_oauth2_token**
+
+------------------------------------------------------------------------
+
+## Endpoint
+
+**POST** `/store-external-oauth2-token/:account_id`\
+**Operation ID:** `store_external_oauth2_token`
+
+This endpoint stores OAuth2 tokens or OAuth2 configuration references
+for the specified account.
+
+------------------------------------------------------------------------
+
+## Request Body: `ExternalOAuth2Request`
+
+``` json
+{
+  "oauth2_id": 123,
+  "access_token": "ACCESS_TOKEN",
+  "refresh_token": "REFRESH_TOKEN"
+}
+```
+
+  -----------------------------------------------------------------------
+  Field                          Type               Description
+  ------------------------------ ------------------ ---------------------
+  `oauth2_id`                    number?            Optional. References
+                                                    an existing OAuth2
+                                                    configuration already
+                                                    stored in Bichon.
+
+  `access_token`                 string?            OAuth2 access token
+                                                    used for
+                                                    authenticating
+                                                    requests to the
+                                                    provider.
+
+  `refresh_token`                string?            OAuth2 refresh token
+                                                    used to obtain new
+                                                    access tokens.
+  -----------------------------------------------------------------------
+
+------------------------------------------------------------------------
+
+## Usage Modes
+
+This endpoint supports two different usage patterns depending on what
+data is provided.
+
+### 1. Providing Only `access_token` (No Automatic Refresh)
+
+Use this mode when OAuth2 authentication is fully handled outside
+Bichon.
+
+-   Bichon stores the access token as-is.
+-   **No automatic token refreshing** is possible.
+-   You must periodically call this endpoint again when the token
+    expires.
+
+#### Example
+
+``` json
+{
+  "access_token": "ACCESS_TOKEN_FROM_PROVIDER"
+}
+```
+
+------------------------------------------------------------------------
+
+### 2. Providing `oauth2_id` + `refresh_token` (Automatic Refresh Enabled)
+
+Use this mode when the OAuth2 authorization flow was completed
+externally, but you want Bichon to manage refreshing.
+
+Requirements:
+
+-   An OAuth2 configuration must already exist in Bichon.
+-   You must provide its ID (`oauth2_id`).
+-   You must include a valid `refresh_token`.
+
+In this mode:
+
+-   Bichon automatically fetches new access tokens when needed.
+-   You no longer need to update tokens manually.
+
+#### Example
+
+``` json
+{
+  "oauth2_id": 12,
+  "refresh_token": "EXTERNAL_REFRESH_TOKEN"
+}
+```