diff --git a/baton/datadog.mdx b/baton/datadog.mdx
index e95b2c90..4e316e38 100644
--- a/baton/datadog.mdx
+++ b/baton/datadog.mdx
@@ -36,15 +36,28 @@ If your user has a custom Datadog role, make sure it includes the **User App Key
 
 ### Locate your Datadog site
 
+Your Datadog site determines which regional API endpoint the connector uses. Identify your site from your Datadog URL:
+
+| Datadog URL | Site value |
+| :--- | :--- |
+| `https://app.datadoghq.com` | `datadoghq.com` |
+| `https://app.datadoghq.eu` | `datadoghq.eu` |
+| `https://app.us3.datadoghq.com` | `us3.datadoghq.com` |
+| `https://app.us5.datadoghq.com` | `us5.datadoghq.com` |
+| `https://app.ddog-gov.com` | `ddog-gov.com` |
+| `https://app.ap1.datadoghq.com` | `ap1.datadoghq.com` |
+
 <Steps>
   <Step>
-  Navigate to the Datadog login screen and make a note of your Datadog site:
+  Navigate to the Datadog login screen and make a note of your Datadog site from the URL.
 
   </Step>
 </Steps>
 
 ### Create an API key
 
+The API key authenticates requests to the Datadog API.
+
 <Steps>
   <Step>
   Log into Datadog account and click **User Account** > **Organizational Settings**.
@@ -64,6 +77,8 @@ If your user has a custom Datadog role, make sure it includes the **User App Key
 
 ### Create an application key
 
+The application key works with the API key to control which API endpoints are accessible. Application keys inherit the permissions of the user who creates them by default, but you can restrict them to specific scopes.
+
 <Steps>
   <Step>
   Navigate back to **Organization Settings**.
@@ -81,6 +96,51 @@ If your user has a custom Datadog role, make sure it includes the **User App Key
   </Step>
 </Steps>
 
+<Tip>
+If you configure scopes on the application key, the connector requires the following scopes at minimum:
+
+- **Access Management** — read and manage users and roles
+- **Teams** — read team information and membership
+
+If scopes are not configured, the application key inherits all permissions of the user who created it.
+</Tip>
+
+### Validate your credentials
+
+After creating your keys, verify they work before configuring the connector.
+
+<Steps>
+<Step>
+Run the following command, replacing the placeholders with your API key, application key, and site:
+
+```bash
+curl -s -X GET "https://api.<your-site>/api/v1/validate" \
+  -H "DD-API-KEY: <your-api-key>" \
+  -H "DD-APPLICATION-KEY: <your-app-key>"
+```
+
+For example, if your site is `datadoghq.com`:
+
+```bash
+curl -s -X GET "https://api.datadoghq.com/api/v1/validate" \
+  -H "DD-API-KEY: <your-api-key>" \
+  -H "DD-APPLICATION-KEY: <your-app-key>"
+```
+</Step>
+<Step>
+A successful response returns:
+
+```json
+{"valid": true}
+```
+
+If you see `{"valid": false}` or an authentication error, verify:
+- The API key and application key are correct and have not been revoked
+- The site value matches your Datadog instance
+- The application key has the required scopes (**Access Management** and **Teams**)
+</Step>
+</Steps>
+
 **Done.** Next, move on to the connector configuration instructions.
 
 ## Configure the Datadog connector
@@ -273,4 +333,22 @@ spec:
 </Tab>
 </Tabs>
 
+## Troubleshooting Datadog authentication
+
+### The connector reports "API key not valid"
+
+The connector validates both the API key and application key at startup. If you see this error:
+
+1. Verify the API key has not been revoked. In Datadog, go to **Organization Settings** > **API Keys** and check that the key is still listed.
+2. Verify the application key has not been revoked. Go to **Organization Settings** > **Application Keys** and check that the key is still listed.
+3. Confirm the site value matches your Datadog instance. An incorrect site causes API calls to reach the wrong regional endpoint, resulting in authentication failures.
+
+### The connector syncs users but not teams or roles
+
+If the connector authenticates successfully but fails to sync certain resources, the application key may lack the required scopes:
+
+1. In Datadog, go to **Organization Settings** > **Application Keys**.
+2. Click the application key used by the connector.
+3. Verify that the **Access Management** and **Teams** scopes are included. If scopes are not configured, the key inherits all permissions of the user who created it — verify that user has the **Datadog Admin** or **Datadog Standard** role.
+
 
diff --git a/baton/linear.mdx b/baton/linear.mdx
index 07687764..63defa42 100644
--- a/baton/linear.mdx
+++ b/baton/linear.mdx
@@ -22,6 +22,14 @@ This connector can also be configured to automatically create and update Linear
 
 Configuring the connector requires you to pass in credentials generated in Linear. Gather these credentials before you move on.
 
+### Prerequisites
+
+<Warning>
+The user who generates the API key must have the **Admin** or **Owner** role in the Linear workspace. The API key inherits all permissions of the user who creates it.
+
+If provisioning is enabled (inviting users, suspending users, managing team membership), the key creator must have **Admin** or **Owner** access.
+</Warning>
+
 ### Generate a new Linear API key
 
 <Steps>
@@ -36,6 +44,36 @@ In the **Personal API keys** section of the page, enter a label such as "C1" and
 </Step>
 <Step>
 The new API key is generated for you. Carefully copy and save the API key.
+
+<Warning>
+Linear only displays the API key once. If you lose it, you must delete the key and create a new one.
+</Warning>
+</Step>
+</Steps>
+
+### Validate your API key
+
+After creating your API key, verify it works before configuring the connector.
+
+<Steps>
+<Step>
+Open a terminal and run the following command, replacing `<your-api-key>` with your key:
+
+```bash
+curl -s -H "Authorization: <your-api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"{ viewer { id name email } }"}' \
+  https://api.linear.app/graphql
+```
+</Step>
+<Step>
+A successful response returns your user details:
+
+```json
+{"data":{"viewer":{"id":"...","name":"Your Name","email":"you@example.com"}}}
+```
+
+If you see an authentication error, verify that you copied the full API key and that the key has not been revoked.
 </Step>
 </Steps>
 
@@ -233,4 +271,21 @@ Check that the connector data uploaded correctly. In C1, click **Apps**. On the
 </Tab>
 </Tabs>
 
+## Troubleshooting Linear authentication
+
+### The connector fails to authenticate
+
+The connector validates your API key at startup by querying the Linear API. If you see `failed to authenticate` in the connector logs:
+
+1. Verify the API key is correct and has not been revoked. In Linear, go to **Settings** > **Security & access** > **Personal API keys** and check that the key is still listed.
+2. Generate a new API key if needed and update the connector configuration.
+
+### The connector cannot provision access
+
+If sync works but provisioning operations fail, the API key may belong to a user without sufficient permissions:
+
+1. Verify the user who created the API key has the **Admin** or **Owner** role in Linear.
+2. Members and Guests cannot perform provisioning operations such as inviting users, suspending accounts, or managing team membership.
+3. If needed, have an Admin or Owner generate a new API key.
+
 
diff --git a/baton/salesforce.mdx b/baton/salesforce.mdx
index 9e93e716..8d343ab0 100644
--- a/baton/salesforce.mdx
+++ b/baton/salesforce.mdx
@@ -53,6 +53,21 @@ Connector actions are custom capabilities that extend C1 automations with app-sp
 |-------------|-------------------|-------------|
 | update_user_status | `resource_id` (string, required) <br/>`is_active` (Boolean, required) | Updates a Salesforce user's status to active or inactive |
 
+## Choose an authentication method
+
+The Salesforce connector supports four authentication methods. Choose the method that best fits your security requirements and environment.
+
+| Method | Best for | Requires |
+| :--- | :--- | :--- |
+| **JWT Bearer** | Production environments, automated deployments | External Client App, X.509 certificate, private key |
+| **Client Credentials** | Service-to-service, no user context needed | External Client App, client ID and secret |
+| **OAuth** | Interactive setup, quick evaluation | Salesforce login via browser |
+| **Username and password** *(deprecated)* | Legacy environments only | Username, password, security token |
+
+<Tip>
+For production deployments, Salesforce recommends **JWT Bearer** or **Client Credentials**. Salesforce is actively disabling SOAP API login for new orgs, which affects username/password authentication.
+</Tip>
+
 ## Gather Salesforce credentials 
 
 Configuring the connector requires you to pass in credentials generated in Salesforce. Gather these credentials before you move on. 
@@ -199,6 +214,54 @@ Go to the **Settings** tab, expand **OAuth Configuration**, and click **Consumer
 
 **Done.** You now have a Consumer Key and Consumer Secret to use with the Client Credentials authentication method.
 
+### Validate your Salesforce credentials
+
+After creating your credentials, verify they work before configuring the connector.
+
+<Tabs>
+<Tab title="JWT Bearer">
+Run the following command, replacing the placeholders with your values:
+
+```bash
+curl -s -X POST https://login.salesforce.com/services/oauth2/token \
+  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
+  -d "assertion=$(YOUR_JWT_ASSERTION)"
+```
+
+To generate the JWT assertion, you need to sign a JWT with your private key. If you have `openssl` and `jq` available, verify you can exchange credentials for a token by checking that your Consumer Key and private key are valid in your Salesforce External Client App configuration.
+
+A successful response returns an `access_token` and `instance_url`. If you see `invalid_grant`, verify:
+- The Consumer Key matches your External Client App
+- The certificate uploaded to Salesforce corresponds to your private key
+- The JWT subject is a valid Salesforce username with the correct profile pre-authorized
+- The JWT Bearer flow is enabled in the app's policies
+</Tab>
+<Tab title="Client Credentials">
+Run the following command, replacing the placeholders with your values:
+
+```bash
+curl -s -X POST https://<your-domain>.my.salesforce.com/services/oauth2/token \
+  -d "grant_type=client_credentials" \
+  -d "client_id=<consumer-key>" \
+  -d "client_secret=<consumer-secret>"
+```
+
+A successful response returns an `access_token` and `instance_url`:
+
+```json
+{"access_token":"00D...","instance_url":"https://your-domain.my.salesforce.com","...":"..."}
+```
+
+If you see `invalid_client`, verify:
+- The Consumer Key and Consumer Secret are correct
+- The Client Credentials flow is enabled in the app's policies
+- The **Run As** username is set in the OAuth Policies section
+</Tab>
+<Tab title="OAuth">
+OAuth credentials are validated during the interactive login flow in C1. No separate validation step is needed.
+</Tab>
+</Tabs>
+
 ## Configure the Salesforce connector
 
 <Warning>