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

# Directory Integration

The co-mind.ai platform supports external identity providers for enterprise authentication. Users can authenticate via LDAP/Active Directory or Microsoft Entra ID (formerly Azure AD) without needing local credentials.

<Note>
  All directory admin endpoints require **JWT authentication** with **Admin** role.
</Note>

## How It Works

When a user logs in via `POST /v1/auth/login`, the platform checks if their email domain matches a configured Identity Provider (IdP). If a match is found, the authentication request is automatically routed to the appropriate directory — no client-side changes needed.

## LDAP / Active Directory

### IdP Configuration Endpoints

| Endpoint                     | Method | Purpose                       |
| ---------------------------- | ------ | ----------------------------- |
| `/v1/admin/idp-configs`      | GET    | List all IdP configurations   |
| `/v1/admin/idp-configs`      | POST   | Create an IdP configuration   |
| `/v1/admin/idp-configs/{id}` | GET    | Get IdP configuration details |
| `/v1/admin/idp-configs/{id}` | PUT    | Update IdP configuration      |
| `/v1/admin/idp-configs/{id}` | DELETE | Delete IdP configuration      |

### Create LDAP Configuration

```bash theme={null}
curl -X POST https://your-instance/v1/admin/idp-configs \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate LDAP",
    "type": "ldap",
    "domain": "example.com",
    "server_url": "ldaps://ldap.example.com:636",
    "bind_dn": "cn=admin,dc=example,dc=com",
    "bind_password": "admin_password",
    "base_dn": "ou=users,dc=example,dc=com",
    "user_filter": "(uid={{username}})"
  }'
```

### Directory Sync & Testing

| Endpoint                                   | Method | Purpose                 |
| ------------------------------------------ | ------ | ----------------------- |
| `/v1/admin/directory/{id}/test-connection` | POST   | Test LDAP/AD connection |
| `/v1/admin/directory/{id}/sync`            | POST   | Trigger directory sync  |
| `/v1/admin/directory/{id}/sync-status`     | GET    | Get sync job status     |

### Test Connection

Before going live, verify the connection:

```bash theme={null}
curl -X POST https://your-instance/v1/admin/directory/IDP_CONFIG_ID/test-connection \
  -H "Authorization: Bearer $JWT"
```

### Trigger Directory Sync

Sync users from the directory into the platform:

```bash theme={null}
curl -X POST https://your-instance/v1/admin/directory/IDP_CONFIG_ID/sync \
  -H "Authorization: Bearer $JWT"
```

### Check Sync Status

```bash theme={null}
curl https://your-instance/v1/admin/directory/IDP_CONFIG_ID/sync-status \
  -H "Authorization: Bearer $JWT"
```

## Microsoft Entra ID (Azure AD)

### Entra Configuration Endpoints

| Endpoint                                       | Method | Purpose                    |
| ---------------------------------------------- | ------ | -------------------------- |
| `/v1/admin/entra-configs`                      | GET    | List Entra configurations  |
| `/v1/admin/entra-configs`                      | POST   | Create Entra configuration |
| `/v1/admin/entra-configs/{id}`                 | GET    | Get Entra configuration    |
| `/v1/admin/entra-configs/{id}`                 | PUT    | Update Entra configuration |
| `/v1/admin/entra-configs/{id}`                 | DELETE | Delete Entra configuration |
| `/v1/admin/entra-configs/{id}/test-connection` | POST   | Test Entra connection      |

### Create Entra Configuration

```bash theme={null}
curl -X POST https://your-instance/v1/admin/entra-configs \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate Azure AD",
    "tenant_id": "your-azure-tenant-id",
    "client_id": "your-app-registration-client-id",
    "client_secret": "your-client-secret",
    "domain": "example.com"
  }'
```

### Test Entra Connection

```bash theme={null}
curl -X POST https://your-instance/v1/admin/entra-configs/CONFIG_ID/test-connection \
  -H "Authorization: Bearer $JWT"
```

### SSO Login Flow

Users authenticated via Entra ID use the SSO endpoint:

```bash theme={null}
curl -X POST https://your-instance/v1/auth/sso \
  -H "Content-Type: application/json" \
  -d '{
    "oid": "entra-object-id",
    "tid": "entra-tenant-id",
    "upn": "user@example.com"
  }'
```

## Service Endpoints

These endpoints support the OAuth/PKCE flow for client applications:

| Endpoint                      | Method | Purpose                                           |
| ----------------------------- | ------ | ------------------------------------------------- |
| `/v1/services/entra-config`   | GET    | Discover tenant Entra config (no secrets exposed) |
| `/v1/services/token/exchange` | POST   | Exchange auth code for tokens (PKCE)              |
| `/v1/services/token/refresh`  | POST   | Refresh OAuth access token                        |

<Tip>
  The `/v1/services/entra-config` endpoint is safe to call from client-side code — it only returns the `client_id` and `tenant_id`, never secrets.
</Tip>