Add auth setup, validation, and troubleshooting for Linear, Salesforce, and Datadog

baton/datadog.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Set up a Datadog connector"
 og:title: "Set up a Datadog connector"
 description: "C1 provides identity governance for Datadog. Integrate your Datadog instance with C1 to run user access reviews (UARs) and enable just-in-time access requests."
 og:description: "C1 provides identity governance for Datadog. Integrate your Datadog instance with C1 to run user access reviews (UARs) and enable just-in-time access requests."
 sidebarTitle: "Datadog"
 ---
 
 <Tip>
 **This is an updated and improved version of the Datadog connector!** If you're setting up Datadog with C1 for the first time, you're in the right place.
 </Tip>
 
 ## Capabilities
@@ -24,30 +24,43 @@
 
 *Schedules are not synced by default, but you can opt into syncing them when configuring the connector.
 
 ## Gather Datadog credentials
 
 Configuring the connector requires you to pass in credentials generated in Datadog. Gather these credentials before you move on.
 
 <Warning>
 A user with the **Connector Administrator** or **Super Administrator** role in C1 and the **Datadog Admin** or **Datadog standard** role in Datadog must perform this task.
 
 If your user has a custom Datadog role, make sure it includes the **User App Keys** and **API Keys Read** permissions.
 </Warning>
 
 ### 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**.
   </Step>
   <Step>
   Click **API Keys** and then click **+ New Key**.
@@ -64,6 +77,8 @@
 
 ### 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,15 +96,60 @@
   </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
 
 <Warning>
 To complete this task, you'll need:
 
 - The **Connector Administrator** or **Super Administrator** role in C1
 - Access to the set of Datadog credentials generated by following the instructions above
 </Warning>
 
 <Tabs>
@@ -105,7 +165,7 @@
   Search for **Datadog v2** and click **Add**.
   </Step>
   <Step>
   Choose how to set up the new Datadog connector:
     - Add the connector to a currently unmanaged app (select from the list of apps that were discovered in your identity, SSO, or federation provider that aren't yet managed with C1)
     - Add the connector to a managed app (select from the list of existing managed apps)
     - Create a new managed app
@@ -122,7 +182,7 @@
   Find the **Settings** area of the page and click **Edit**.
   </Step>
   <Step>
   Select your Datadog site from the list.
   </Step>
   <Step>
   Paste the API key into the **API key** field.
@@ -144,12 +204,12 @@
   </Step>
 </Steps>
 
 **Done.** Your Datadog connector is now pulling access data into C1.
 
 </Tab>
 <Tab title="Self-hosted">
 
 **Follow these instructions to use the Datadog connector, hosted and run in your own environment.**
 
 When running in service mode on Kubernetes, a self-hosted connector maintains an ongoing connection with C1, automatically syncing and uploading data at regular intervals. This data is immediately available in the C1 UI for access reviews and access requests.
 
@@ -159,7 +219,7 @@
 
 * [GitHub repository](https://github.com/conductorone/baton-datadog): Access the source code, report issues, or contribute to the project.
 
 ### Step 1: Set up a new Datadog connector
 
 <Steps>
   <Step>
@@ -169,8 +229,8 @@
   Search for **Baton** and click **Add**.
   </Step>
   <Step>
   Choose how to set up the new Datadog connector:
     - Add the connector to a currently unmanaged app (select from the list of apps that were discovered in your identity, SSO, or federation provider that aren't yet managed with C1)
     - Add the connector to a managed app (select from the list of existing managed apps)
     - Create a new managed app
   </Step>
@@ -194,7 +254,7 @@
 
 ### Step 2: Create Kubernetes configuration files
 
 Create two Kubernetes manifest files for your Datadog connector deployment:
 
 #### Secrets configuration
 
@@ -261,16 +321,34 @@
 
 <Steps>
   <Step>
   Create a namespace in which to run C1 connectors (if desired), then apply the secret config and deployment config files.
   </Step>
   <Step>
   Check that the connector data uploaded correctly. In C1, click **Apps**. On the **Managed apps** tab, locate and click the name of the application you added the Datadog connector to. Datadog data should be found on the **Entitlements** and **Accounts** tabs.
   </Step>
 </Steps>
 
 **Done.** Your Datadog connector is now pulling access data into C1.
 
 </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.
+
 

baton/linear.mdx

@@ -2,7 +2,7 @@
 title: "Set up a Linear connector"
 og:title: "Set up a Linear connector"
 description: "C1 provides identity governance and just-in-time provisioning for Linear. Integrate your Linear instance with C1 to run user access reviews (UARs) and enable just-in-time access requests."
 og:description: "C1 provides identity governance and just-in-time provisioning for Linear. Integrate your Linear instance with C1 to run user access reviews (UARs) and enable just-in-time access requests."
 sidebarTitle: "Linear"
 ---
 
@@ -22,6 +22,14 @@
 
 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 @@
 </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>
 
@@ -64,7 +102,7 @@
 <Step>
 Choose how to set up the new Linear connector:
 
    - Add the connector to a currently unmanaged app (select from the list of apps that were discovered in your identity, SSO, or federation provider that aren't yet managed with C1)
 
    - Add the connector to a managed app (select from the list of existing managed apps)
 
@@ -127,7 +165,7 @@
 <Step>
 Choose how to set up the new Linear connector:
 
    - Add the connector to a currently unmanaged app (select from the list of apps that were discovered in your identity, SSO, or federation provider that aren't yet managed with C1)
 
    - Add the connector to a managed app (select from the list of existing managed apps)
 
@@ -222,7 +260,7 @@
 
 <Steps>
 <Step>
 Create a namespace in which to run C1 connectors (if desired), then apply the secret config and deployment config files.
 </Step>
 <Step>
 Check that the connector data uploaded correctly. In C1, click **Apps**. On the **Managed apps** tab, locate and click the name of the application you added the Linear connector to. Linear data should be found on the **Entitlements** and **Accounts** tabs.
@@ -233,4 +271,21 @@
 </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.
+
 

baton/salesforce.mdx

@@ -1,8 +1,8 @@
 ---
 title: Set up a Salesforce connector
 og:title: Set up a Salesforce connector - C1 docs
 og:description: Integrate your Salesforce instance with C1 to run user access reviews, enable just-in-time access requests, and easily provision and deprovision access.
 description: C1 provides identity governance for Salesforce. Integrate your Salesforce instance with C1 to run user access reviews (UARs) and enable just-in-time access requests.
 sidebarTitle: "Salesforce"
 ---
 
@@ -33,13 +33,13 @@
 
 The Salesforce connector supports [automatic account provisioning](/product/admin/account-provisioning).
 
 This connector does not support account deprovisioning. You must deprovision accounts directly in Salesforce.
 
 **Territories require Enterprise Territory Management 2.0 to be enabled in your Salesforce org. If this feature is not enabled, the connector will return an error when attempting to sync territories.**
 
 ### Optional fields for custom validation rules
 
 Some Salesforce orgs have custom validation rules that require additional fields to be set when creating a user (for example, a rule that requires `FederationIdentifier` for SSO).
 
 To add an optional field mapping in C1, use the exact Salesforce field API name as the mapping key (for example, `FederationIdentifier`, `Department`, `CommunityNickname`) allowing you to satisfy any validation rule.
 
@@ -47,12 +47,27 @@
 
 ### Connector actions
 
 Connector actions are custom capabilities that extend C1 automations with app-specific operations. You can use connector actions in the [Perform connector action](/product/admin/automations-steps-reference#perform-connector-action) automation step.
 
 | Action name | Additional fields | Description |
 |-------------|-------------------|-------------|
 | 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. 
@@ -132,7 +147,7 @@
 <Step>
 Expand **OAuth Settings** and configure the following:
 - **Callback URL**: enter any valid URL
 - **Selected OAuth Scopes**: add **Full access (full)**, **Manage user data via APIs (api)**, and **Perform requests at any time (refresh_token, offline_access)**
 - Under **Flow Enablement**, check **Enable JWT Bearer Flow**. A **Certificate Upload** field will appear — upload your certificate (`.pem`). You will need the corresponding private key (`.pem`) later when configuring the connector.
 </Step>
 <Step>
@@ -199,6 +214,54 @@
 
 **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>
@@ -450,7 +513,7 @@
 
 <Steps>
 <Step>
 Create a namespace in which to run C1 connectors (if desired), then apply the secret config and deployment config files. 
 </Step>
 <Step>
 Check that the connector data uploaded correctly. In C1, click **Apps**. On the **Managed apps** tab, locate and click the name of the application you added the Salesforce connector to. Salesforce data should be found on the **Entitlements** and **Accounts** tabs.