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

# Azure DevOps (Direct OAuth)

Connect Azure DevOps to Athena to browse projects, search and read work items,
and create or update them from chat — each member acting as their own Microsoft
Entra identity, so Azure DevOps project permissions apply unchanged.

<Info>
  Setup is two steps, done by two different people: your **Azure administrator**
  registers an app in Entra ID, then an **Athena workspace admin** saves that app
  once for the whole workspace. Members can only connect after both are done.
</Info>

## What connecting Azure DevOps unlocks

* **List projects** and teams in your organization.
* **Search work items** with WIQL, and read individual work items with their
  fields and history.
* **Create and update work items** from chat.
* **List iterations** and the work items in a given sprint.

## Step 1 — Register an Entra ID application (Azure admin)

1. **Azure Portal → Microsoft Entra ID → App registrations → New
   registration**. Name it e.g. `Athena — Azure DevOps`.
2. **Redirect URI**: platform **Web**, value:

   ```
   https://api.athenaintel.com/api/azure-devops-direct/oauth/callback
   ```

   Entra compares redirect URIs as exact strings — trailing slashes and scheme
   mismatches fail the handshake.
3. **API permissions → Add a permission → Azure DevOps → Delegated permissions →
   `user_impersonation`**, then **Grant admin consent** so members aren't prompted
   individually.
4. **Certificates & secrets → New client secret**. Copy the **Value** right away —
   Entra shows it once.
5. **Overview**: copy the **Application (client) ID** and **Directory (tenant)
   ID**.

<Note>
  Your Azure DevOps organization must be connected to the same Entra tenant.
</Note>

## Step 2 — Enable Azure DevOps in Athena (workspace admin, once)

An **Athena workspace admin or owner** must add this on the Athena side for the
**entire workspace** before individual members can connect their Azure DevOps
organizations. Members cannot configure it themselves.

Open **[Workspace Settings → Treasury →
Integrations](https://app.athenaintel.com/dashboard/workspace-settings/treasury/?tab=integrations)**,
expand **Azure DevOps**, toggle it on, and fill in:

| Field                  | Value                                                                |
| ---------------------- | -------------------------------------------------------------------- |
| **Azure AD Tenant ID** | Directory (tenant) ID — restricts sign-in to accounts in this tenant |
| **Client ID**          | Application (client) ID from step 1.5                                |
| **Client Secret**      | The secret **Value** from step 1.4                                   |

The client secret is encrypted before storage and is never returned to the
browser.

## Step 3 — Members connect (each user)

1. Go to **[Integrations](https://app.athenaintel.com/dashboard/integrations/)**
   and click **Azure DevOps → Connect**.
2. Sign in to Microsoft in the popup and consent to **Azure DevOps
   user\_impersonation**.
3. Pick the Azure DevOps organization you want. Athena creates a private catalog
   for you, and the Azure DevOps tools become available in chat.

## Troubleshooting

| Symptom                                                 | Cause and fix                                                                                                                    |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `redirect_uri_mismatch` in the popup                    | The callback URL isn't registered on the Entra app, or doesn't match exactly.                                                    |
| Sign-in succeeds but no organizations are listed        | Your Azure DevOps organization isn't connected to that Entra tenant, or the member isn't a member of it.                         |
| Work items are readable but creating one fails          | The connected member lacks project-level write permission in Azure DevOps. Permissions are enforced by Azure DevOps, not Athena. |
| No Azure DevOps connect option on the Integrations page | A workspace admin hasn't completed step 2.                                                                                       |

<Tip>
  Tokens are per-user, encrypted at rest, and refreshed automatically. You can
  disconnect at any time from the Integrations page.
</Tip>