📝 Session Token Authenticator documentation (#28762)

* add documentation for session token authenticator

* fix refresh token statements in compatibility guide

* add blurb about session token auth to compatibility guide

* spell out keys and values

* add a couple more comments

docs/connector-development/connector-builder-ui/authentication.md

@@ -17,6 +17,7 @@ Check the documentation of the API you want to integrate for the used authentica
 * [Bearer Token](#bearer-token)
 * [API Key](#api-key)
 * [OAuth](#oauth)
+* [Session Token](#session-token)
 
 Select the matching authentication method for your API and check the sections below for more information about individual methods.
 
@@ -143,6 +144,50 @@ In a lot of cases, OAuth refresh tokens are long-lived and can be used to create
 
 This can be done using the "Overwrite config with refresh token response" setting. If enabled, the authenticator expects a new refresh token to be returned from the token refresh endpoint. By default, the property `refresh_token` is used to extract the new refresh token, but this can be configured using the "Refresh token property name" setting. The connector then updates its own configuration with the new refresh token and uses it the next time an access token needs to be generated. If this option is used, it's necessary to specify an initial access token along with its expiry date in the "Testing values" menu.
 
+### Session Token
+Some APIs require callers to first fetch a unique token from one endpoint, then make the rest of their calls to all other endpoints using that token to authenticate themselves. These tokens usually have an expiration time, after which a new token needs to be re-fetched to continue making requests. This flow can be achieved through using the Session Token Authenticator.
+
+If requests are authenticated using the Session Token authentication method, the API documentation page will likely contain one of the following keywords:
+- "Session Token"
+- "Session ID"
+- "Auth Token"
+- "Access Token"
+- "Temporary Token"
+
+#### Configuration
+The configuration of a Session Token authenticator is a bit more involved than other authenticators, as you need to configure both how to make requests to the session token retrieval endpoint (which requires its own authentication method), as well as how the token is extracted from that response and used for the data requests.
+
+We will walk through each part of the configuration below. Throughout this, we will refer to the [Metabase API](https://www.metabase.com/learn/administration/metabase-api#authenticate-your-requests-with-a-session-token) as an example of an API that uses session token authentication.
+- `Session Token Retrieval` - this is a group of fields which configures how the session token is fetched from the session token endpoint in your API. Once the session token is retrieved, your connector will reuse that token until it expires, at which point it will retrieve a new session token using this configuration.
+  - `URL` - the full URL of the session token endpoint
+    - For Metabase, this would be `https://<app_name>.metabaseapp.com/api/session`.
+  - `HTTP Method` - the HTTP method that should be used when retrieving the session token endpoint, either `GET` or `POST`
+    - Metabase requires `POST` for its `/api/session` requests.
+  - `Authentication Method` - configures the method of authentication to use **for the session token retrieval request only**
+    - Note that this is separate from the parent Session Token Authenticator. It contains the same options as the parent Authenticator Method dropdown, except for OAuth (which is unlikely to be used for obtaining session tokens) and Session Token (as it does not make sense to nest). 
+    - For Metabase, the `/api/session` endpoint takes in a `username` and `password` in the request body. Since this is a non-standard authentication method, we must set this inner `Authentication Method` to `No Auth`, and instead configure the `Request Body` to pass these credentials (discussed below).
+  - `Query Parameters` - used to attach query parameters to the session token retrieval request
+    - Metabase does not require any query parameters in the `/api/session` request, so this is left unset.
+  - `Request Headers` - used to attach headers to the sesssion token retrieval request
+    - Metabase does not require any headers in the `/api/session` request, so this is left unset.
+  - `Request Body` - used to attach a request body to the session token retrieval request
+    - As mentioned above, Metabase requires the username and password to be sent in the request body, so we can select `JSON (key-value pairs)` here and set the username and password fields (using User Inputs for the values to make the connector reusable), so this would end up looking like:
+      - Key: `username`, Value: `{{ config['username'] }}`
+      - Key: `password`, Value: `{{ config['password'] }}`
+  - `Error Handler` - used to handle errors encountered when retrieving the session token
+    - See the [Error Handling](/connector-development/connector-builder-ui/error-handling) page for more info about configuring this component.
+- `Session Token Path` - an array of values to form a path into the session token retrieval response which points to the session token value
+  - For Metabase, the `/api/session` response looks like `{"id":"<session-token-value>"}`, so the value here would simply be `id`.
+- `Expiration Duration` - an [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) indicating how long the session token has until it expires
+  - Once this duration is reached, your connector will automatically fetch a new session token, and continue making data requests with that new one.
+  - If this is left unset, the session token will be refreshed before every single data request. This is **not recommended** if it can be avoided, as this will cause the connector to run much slower, as it will need to make an extra token request for every data request.
+  - Note: this **does _not_ support dynamic expiration durations of session tokens**. If your token expiration duration is dynamic, you should set the `Expiration Duration` field to the expected minimum duration to avoid problems during syncing.
+  - For Metabase, the token retrieved from the `/api/session` endpoint expires after 14 days by default, so this value can be set to `P2W` or `P14D`.
+- `Data Request Authentication` - configures how the session token is used to authenticate the data requests made to the API
+  - Choose `API Key` if your session token needs to be injected into a query parameter or header of the data requests.
+    - Metabase takes in the session token through a specific header, so this would be set to `API Key`, Inject Session Token into outgoing HTTP Request would be set to `Header`, and Header Name would be set to `X-Metabase-Session`.
+  - Choose `Bearer` if your session token needs to be sent as a standard Bearer token.
+
 ### Custom authentication methods
 
 Some APIs require complex custom authentication schemes involving signing requests or doing multiple requests to authenticate. In these cases, it's required to use the [low-code CDK](/connector-development/config-based/low-code-cdk-overview) or [Python CDK](/connector-development/cdk-python/).

docs/connector-development/connector-builder-ui/connector-builder-compatibility.md

@@ -113,28 +113,16 @@ Are requests authenticated using an OAuth2.0 flow with a refresh token grant typ
 
 Examples: [Square](https://developer.squareup.com/docs/oauth-api/overview), [Woocommerce](https://woocommerce.github.io/woocommerce-rest-api-docs/#introduction)
 
-#### Is the OAuth refresh token long-lived?
-Using [Gitlab](https://docs.gitlab.com/ee/api/oauth2.html) as an example, you can tell it uses an ephemeral refresh token because the authorization request returns a new refresh token in addition to the access token. This indicates a new refresh token should be used next time.
+If the refresh request requires custom query parameters or request headers, use the Python CDK.<br/>
+If the refresh request requires a [grant type](https://oauth.net/2/grant-types/) that is not "Refresh Token" or "Client Credentials", such as an Authorization Code, or a PKCE, use the Python CDK.<br/>
+If the authentication mechanism is OAuth flow 2.0 with refresh token or client credentials and does not require custom query params, it is compatible with the Connector Builder.
 
-Example response:
-```
-{
-    "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
-    "token_type": "bearer",
-    "expires_in": 7200,
-    "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
-    "created_at": 1607635748
-}
-```
+### Session Token
+Are data requests authenticated using a temporary session token that is obtained through a separate request?
 
-Example:
-- Yes: [Gitlab](https://docs.gitlab.com/ee/api/oauth2.html)
-- No: [Square](https://developer.squareup.com/docs/oauth-api/overview), [Woocommerce](https://woocommerce.github.io/woocommerce-rest-api-docs/#introduction)
+Examples: [Metabase](https://www.metabase.com/learn/administration/metabase-api#authenticate-your-requests-with-a-session-token), [Splunk](https://dev.splunk.com/observability/reference/api/sessiontokens/latest)
 
-If the OAuth flow requires a single-use refresh token, use the Python CDK.
-If the refresh request requires custom query parameters or request headers, use the Python CDK.
-If the refresh request requires a [grant type](https://oauth.net/2/grant-types/) that is not "Refresh Token", such as an Authorization Code, or a PKCE, use the Python CDK. 
-If the authentication mechanism is OAuth flow 2.0 with refresh token and does not require refreshing the refresh token or custom query params, it is compatible with the Connector Builder.
+If the authentication mechanism is a session token obtained through calling a separate endpoint, and which expires after some amount of time and needs to be re-obtained, it is compatible with the Connector Builder.
 
 ### Other
 AWS endpoints are examples of APIs requiring a non-standard authentication mechanism. You can tell from [the documentation](https://docs.aws.amazon.com/pdfs/awscloudtrail/latest/APIReference/awscloudtrail-api.pdf#Welcome) that requests need to be signed with a hash.