> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.airweave.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airweave.ai/_mcp/server.
# Zendesk
> Zendesk integration with Airweave
{/* AUTO-GENERATED CONTENT START */}
Zendesk
This connector enables AI agents and RAG systems to retrieve context from Zendesk through Airweave's unified search layer.
## Configuration
Zendesk source connector integrates with the Zendesk API to extract and synchronize data.
Connects to your Zendesk instance to sync tickets, comments, users, orgs, and attachments.
#### [View Source Code](https://github.com/airweave-ai/airweave/tree/main/backend/airweave/platform/sources/zendesk.py)
Explore the Zendesk connector implementation
### Authentication
This connector uses **OAuth 2.0 with custom credentials**. You need to provide your OAuth application's Client ID and Client Secret, then complete the OAuth consent flow.
#### OAuth Setup Required
1. Create an OAuth application in your provider's developer console
2. Enter your Client ID and Client Secret when configuring the connection
3. Complete the OAuth consent flow
### Configuration Options
This connector does not have any additional configuration options.
## Data Models
The following data models are available for this connector:
#### ZendeskTicketEntity
Schema for Zendesk ticket entities.
Reference:
[https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/)
| Field | Type | Description |
| ------------------ | ---------------------- | ------------------------------------------------------ |
| ticket\_id | int | Unique identifier of the ticket |
| subject | str | The subject of the ticket |
| created\_time | datetime | When the ticket was created. |
| updated\_time | datetime | When the ticket was last updated. |
| web\_url\_value | Optional\[str] | UI URL to open the ticket in Zendesk. |
| description | Optional\[str] | The description of the ticket (first comment) |
| requester\_id | Optional\[int] | ID of the user who requested the ticket |
| requester\_name | Optional\[str] | Name of the user who requested the ticket |
| requester\_email | Optional\[str] | Email of the user who requested the ticket |
| assignee\_id | Optional\[int] | ID of the user assigned to the ticket |
| assignee\_name | Optional\[str] | Name of the user assigned to the ticket |
| assignee\_email | Optional\[str] | Email of the user assigned to the ticket |
| status | str | Current status of the ticket |
| priority | Optional\[str] | Priority level of the ticket |
| tags | List\[str] | Tags associated with the ticket |
| custom\_fields | List\[Dict\[str, Any]] | Custom field values for the ticket |
| organization\_id | Optional\[int] | ID of the organization associated with the ticket |
| organization\_name | Optional\[str] | Name of the organization associated with the ticket |
| group\_id | Optional\[int] | ID of the group the ticket belongs to |
| group\_name | Optional\[str] | Name of the group the ticket belongs to |
| ticket\_type | Optional\[str] | Type of the ticket (question, incident, problem, task) |
| url | Optional\[str] | URL to view the ticket in Zendesk |
#### ZendeskCommentEntity
Schema for Zendesk comment entities.
Reference:
[https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-comments/](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-comments/)
| Field | Type | Description |
| --------------- | ---------------------- | ------------------------------------------------ |
| comment\_id | int | Unique identifier of the comment |
| ticket\_id | int | ID of the ticket this comment belongs to |
| ticket\_subject | str | Subject of the ticket this comment belongs to |
| author\_id | int | ID of the user who wrote the comment |
| author\_name | str | Name of the user who wrote the comment |
| author\_email | Optional\[str] | Email of the user who wrote the comment |
| body | str | The content of the comment |
| html\_body | Optional\[str] | HTML formatted content of the comment |
| public | bool | Whether the comment is public or internal |
| attachments | List\[Dict\[str, Any]] | Attachments associated with this comment |
| created\_time | datetime | When the comment was created. |
| web\_url\_value | Optional\[str] | URL to view this comment (falls back to ticket). |
#### ZendeskUserEntity
Schema for Zendesk user entities.
Reference:
[https://developer.zendesk.com/api-reference/ticketing/users/users/](https://developer.zendesk.com/api-reference/ticketing/users/users/)
| Field | Type | Description |
| ------------------ | ---------------------- | -------------------------------------------- |
| user\_id | int | Unique identifier of the user |
| display\_name | str | Display name of the user. |
| created\_time | datetime | When the user was created. |
| updated\_time | datetime | When the user was last updated. |
| web\_url\_value | Optional\[str] | URL to the user's profile in Zendesk. |
| email | str | Email address of the user |
| role | str | Role of the user (end-user, agent, admin) |
| active | bool | Whether the user account is active |
| last\_login\_at | Optional\[Any] | When the user last logged in |
| organization\_id | Optional\[int] | ID of the organization the user belongs to |
| organization\_name | Optional\[str] | Name of the organization the user belongs to |
| phone | Optional\[str] | Phone number of the user |
| time\_zone | Optional\[str] | Time zone of the user |
| locale | Optional\[str] | Locale of the user |
| custom\_fields | List\[Dict\[str, Any]] | Custom field values for the user |
| tags | List\[str] | Tags associated with the user |
| user\_fields | Dict\[str, Any] | User-specific custom fields |
| profile\_url | Optional\[str] | API URL to the user resource |
#### ZendeskOrganizationEntity
Schema for Zendesk organization entities.
Reference:
[https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/](https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/)
| Field | Type | Description |
| -------------------- | ---------------------- | --------------------------------------------- |
| organization\_id | int | Unique identifier of the organization |
| organization\_name | str | Display name of the organization. |
| created\_time | datetime | When the organization was created. |
| updated\_time | datetime | When the organization was last updated. |
| web\_url\_value | Optional\[str] | URL to view the organization in Zendesk. |
| domain\_names | List\[str] | Domain names associated with the organization |
| details | Optional\[str] | Details about the organization |
| notes | Optional\[str] | Notes about the organization |
| tags | List\[str] | Tags associated with the organization |
| custom\_fields | List\[Dict\[str, Any]] | Custom field values for the organization |
| organization\_fields | Dict\[str, Any] | Organization-specific custom fields |
| api\_url | Optional\[str] | API URL for this organization resource. |
#### ZendeskAttachmentEntity
Schema for Zendesk attachment entities.
Reference:
[https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/)
| Field | Type | Description |
| --------------- | ---------------------- | ------------------------------------------------ |
| attachment\_id | int | Unique identifier of the attachment |
| ticket\_id | Optional\[int] | ID of the ticket this attachment belongs to |
| comment\_id | Optional\[int] | ID of the comment this attachment belongs to |
| ticket\_subject | Optional\[str] | Subject of the ticket this attachment belongs to |
| content\_type | str | MIME type of the attachment |
| file\_name | str | Original filename of the attachment |
| thumbnails | List\[Dict\[str, Any]] | Thumbnail information for the attachment |
| created\_time | datetime | When the attachment was created. |
| updated\_time | datetime | When the attachment metadata was updated. |
| web\_url\_value | Optional\[str] | URL to download the attachment. |
{/* AUTO-GENERATED CONTENT END */}
## Setting Up Your Zendesk OAuth Application
Zendesk requires you to create your own OAuth application (BYOC - Bring Your Own Credentials) to connect with Airweave. Follow these steps to set up your OAuth client:
### Step 1: Create OAuth Client in Zendesk
1. Log into your Zendesk Admin Center
2. Navigate to **Apps and integrations** → **APIs** → **OAuth clients**
3. Click **Add OAuth client** on the right side
### Step 2: Configure OAuth Client
Fill out the OAuth client form with the following details:
**`Name`** `string` — required
**Example:** `Airweave`
This name will be shown to users during the authorization flow.
---
**`Description`** `string`
**Example:** `Airweave connector for syncing Zendesk data`
Optional description visible during authorization.
---
**`Company`** `string`
**Example:** `Your Company Name`
Helps users understand who they're granting access to.
---
**`Identifier`** `string` — required
**Example:** `airweave`
This becomes your **Client ID**. You can use the auto-generated value or customize it.
---
**`Type client`** `enum` — required
**Must be:** `Confidential`
**Important:** Select "Confidential", not "Public". Public clients will not work with Airweave.
---
**`Redirect URLs`** `string` — required
Enter your Airweave callback URL. Use the appropriate URL for your environment:
* **Production:** `https://api.airweave.ai/source-connections/callback`
* **Local:** `http://localhost:8001/source-connections/callback`
The redirect URL must match exactly (including protocol and trailing slashes). For localhost, `http://` is required.
---
### Step 3: Save and Generate Secret
1. Click **Save**
2. After saving, a **Secret** field will appear with your client secret
3. **Copy the entire secret** immediately - it will only be shown once in full
4. Click **Save** again to finalize
**Security Note:** The client secret will only be displayed fully once. After clicking Save, you'll only see the first 9 characters. Store it securely!
### Step 4: Activate the OAuth Client
1. Find your OAuth client in the OAuth clients list
2. Change the **Status** from **Inactive** to **Active**
3. Save the changes
The OAuth client must be in "Active" status to accept authorization requests. If it's inactive, you'll receive an "Invalid Authorization Request" error.
### Step 5: Configure in Airweave
When creating a Zendesk connection in Airweave, you'll need to provide:
1. **Subdomain:** Your Zendesk subdomain only (e.g., `mycompany` NOT `mycompany.zendesk.com`)
2. **Client ID:** The identifier you set in Step 2
3. **Client Secret:** The secret you copied in Step 3
#### Example Configuration
```json
{
"config": {
"subdomain": "mycompany"
},
"authentication": {
"client_id": "airweave",
"client_secret": "your-secret-here"
}
}
```
## Troubleshooting
#### Invalid Authorization Request Error
**Cause:** Your OAuth client is inactive or misconfigured.
**Solution:**
* Verify the OAuth client status is "Active"
* Ensure the client type is set to "Confidential"
* Check that the redirect URL exactly matches your Airweave callback URL
#### Client Secret Not Working
**Cause:** Incomplete secret copied or secret regenerated.
**Solution:**
* Make sure you copied the entire secret (it may extend past the visible text box)
* If needed, click the "Regenerate" button to generate a new secret
* Copy the new secret immediately and update it in Airweave
#### Redirect URI Mismatch
**Cause:** The redirect URL in your OAuth client doesn't match Airweave's callback URL.
**Solution:**
* Verify the redirect URL is exactly: `https://api.airweave.ai/source-connections/callback`
* Check for trailing slashes, protocol (http/https), and exact domain match
* For local development, ensure you're using `http://` not `https://`
## Required Scopes
Airweave requires the following Zendesk OAuth scopes:
* `read` - Read access to tickets, users, organizations, and comments
* `write` - Write access for updating ticket data (optional, for future features)
These scopes are automatically included in the authorization request.