> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to OpenCX

> Paste Azure AD credentials into the OpenCX dashboard and verify the connection to Dynamics 365.

With the four values from [Azure & Dynamics Setup](/integrations/dynamics-365/azure-setup) in hand, pasting them into OpenCX takes about a minute. **Test & Save Configuration** runs a round-trip against Dynamics to confirm the credentials work before the row is saved.

<Warning>
  **Complete [Azure & Dynamics Setup](/integrations/dynamics-365/azure-setup) first.** Without an Application User on the Dynamics side, Test & Save will fail — the Azure token returns 200 but the Dynamics API call returns 401.
</Warning>

## Paste the credentials

<Steps>
  <Step title="Open the Dynamics 365 integration modal">
    In your [OpenCX dashboard](https://platform.open.cx/settings/integrations), find the **Dynamics 365** card and click **Configure**.
  </Step>

  <Step title="Fill in the four fields">
    | Field               | Where it comes from                                                  |
    | ------------------- | -------------------------------------------------------------------- |
    | **Client ID**       | Azure app registration → Overview → Application (client) ID          |
    | **Client Secret**   | The value you copied when you created the secret (not the Secret ID) |
    | **Tenant ID**       | Azure app registration → Overview → Directory (tenant) ID            |
    | **Environment URL** | `https://yourorg.crm.dynamics.com` (no trailing slash)               |
  </Step>

  <Step title="Click Test & Save Configuration">
    OpenCX runs the verification described below. On success you'll see a confirmation toast and the card flips to **Active**. On failure the save is rejected and nothing is written to the database.
  </Step>
</Steps>

## What "Test & Save" does

<Info>
  Verification is two calls, not one. Both must succeed for the credentials to save.
</Info>

* **Token exchange** — OpenCX POSTs to `https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token` with `grant_type=client_credentials` and `scope=<environment_url>/.default`. A 400 here means Azure AD rejected the tenant/client/secret triple.
* **Dynamics probe** — OpenCX uses the token to `GET <environment_url>/api/data/v9.2/incidents`. A 401 or 403 here means the token is fine but the Application User or its security role isn't.
* **Save** — Only after both calls return 2xx does OpenCX upsert the row into `dynamics365_integration_settings` (encrypted at rest).

## Rotating the client secret

Azure AD client secrets expire. A few days before the expiry:

1. Create a new secret in the same app registration (**Certificates & secrets → New client secret**).
2. Copy the new value.
3. Open the OpenCX Dynamics 365 modal, paste the new secret, and click **Test & Save Configuration**.
4. Delete the old secret in Azure once you've confirmed the new one works.

You don't need to change the tenant ID, client ID, or environment URL — they don't rotate.

## Disconnecting

Opening the modal and removing the settings row deletes the credentials from OpenCX. Incidents and Omnichannel live work items that were already created stay in Dynamics exactly as they are — disconnecting only stops OpenCX from creating new ones.

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    Routing logic, contact dedupe, defaults, and observability.
  </Card>

  <Card title="AI Chat Widget in Dynamics 365" icon="comments" href="/integrations/dynamics-365/channels/widget">
    First channel to try — widget handoff lands as an Omnichannel live work item.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Credential verify fails, unassigned incidents, unlinked contacts.
  </Card>

  <Card title="Azure & Dynamics Setup" icon="microsoft" href="/integrations/dynamics-365/azure-setup">
    App registration, secret, Application User, security role.
  </Card>
</CardGroup>