# Audit Logs

**Sync Type: Incremental**

## Overview

This source connector fetches audit logs events from the Zendesk API.
The audit log shows various changes in a Zendesk account since the account was created.

## Prerequisites

1. Confirm that your Zendesk subscription supports viewing audit logs.
2. A Zendesk account with an Administrator role.
3. The unique Zendesk subdomain associated with the account.

## Limitations
1. Audit Logs are only available for [Enterprise account](https://developer.zendesk.com/api-reference/ticketing/account-configuration/audit_logs/)
2. This input is restricted by [rate limits](https://developer.zendesk.com/api-reference/introduction/rate-limits/).

## Authentication
The following authentication methods are supported by this input:
| Authentication Method             | Documentation 
|-----------------------------------|---------------
| API Token Authentication          | [API Token Authentication](https://support.zendesk.com/hc/en-us/articles4408889192858-Managing-API-token-access-to-the-Zendesk-API#topic_tcb_fk1_2yb)
| OAuth access token authentication | [OAuth access token authentication](https://support.zendesk.com/hc/en-us/articles/4408831452954-How-can-I-authenticate-API-requests)


## API Token Authentication

### Generate API Token

1. Login to Zendesk Admin Center.
2. On the left navigation bar expand the option **Apps and Integrations** and below the **APIs** menu click on **API tokens**.
3. Click on **Add API Token** button on top right.
4. Fill out the description and click on **Save** to generate the API Token.
    - **Copy and store this token. It won't be shown in full again after you leave this page.**
5. On the left navigation bar under **APIs** select **API Configuration** and make sure the `Allow API token access` checkbox is enabled. 

### Configuration

The following fields are specific for the API token authentication method.
|Field      | Description                    |
|-----------|--------------------------------|
| API token | Active API token               |
| Email     | An administrator email address |

## OAuth access token authentication

### Create Client credentials
1. Login to Zendesk Admin Center.
2. On the left navigation bar expand the option **Apps and Integrations** and below the **APIs** menu click on **OAuth clients**.
3. Click on **Add OAuth client** button on top right.
4. Fill out the required fields and click on **Save** to generate the Secret value.
    - Unique identifier is your Client ID.
    - Choose the **Client kind** of type **Confidential**.
    - Add `http://localhost` in **Redirect URLs** field.
    - **Save the secret value as it won't be shown in full again after you leave this page.**

### Create an Oauth authorization flow
1. In a browser, navigate to `https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&client_id={Unique Identifier}&scope=auditlogs:read` to authorize the application.
    - Replace `subdomain` and `Unique Identifier` in the URL with their respective values.
    - Once the page has loaded, click "Allow".

### Locate the OAuth's client ID
1. Zendesk does not provide a UI to get this information, but it is available using the browser's developer tools.
2. Navigate away from the OAuth Clients tab, and then navigate back to the OAuth Clients tab. This will initiate the browser to make a new API request for the OAuth Clients list. This request will have a json response, and in there will be the id that is required. This will be used as the client_id in the next step.

### Create the OAuth access token
1. Make an API request to Zendesk to generate an OAuth Access Token. This access token does not expire and can be used in the configuration of this input.
2. Using an adminitrator's email address and the API Token created above, update the `subdomain`, `client_id`, `email_address` and `api_token` values below, then make the following request:

    ```
    curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
    -X POST \
    -v -u {email_address}/token:{api_token} \
    -H "Content-Type: application/json" \
    -d '{
        "token": {
        "client_id": {client_id},
        "scopes": [
            "auditlogs:read"
        ]
        }
    }'
    ```
3. In the JSON reponse, copy the `full_token` value. This will be the value to use for Access Token field in the input configuration.

## Configuration

### Secrets

| Setting | Type   | Required | Description |
|---------|--------|----------|-------------|
| Token   | string | true     | Either the API token or the Access token generated using OAuth client credentials. |

### Settings

| Setting | Type   | Required | Description |
|---------|--------|----------|-------------|
| Subdomain   | string | true     | This is the subdomain found in the Zendesk URL. |
| Email Address | string | true   | This is the email address registered with your Zendesk account. |
| AuthType | string | true | This is the type of authentication used by the input. |
| API Rate Limit | object | No | Optional limit on the connector's outbound request rate to the source API. Leave blank to use the connector's default behavior. See [API Rate Limiting](../../../guides/rate-limiting) for the field format, limits, and how to choose a value. |

## Sample Audit Log
```json
{
    "url": "https://demo.zendesk.com/api/v2/audit_logs/1234.json",
    "id": 1234,
    "action_label": "Updated",
    "actor_id": -1,
    "source_id": 56765,
    "source_type": "account",
    "source_label": "Contacts: Account owner",
    "action": "update",
    "change_description": "Changed from not set to demo_user",
    "ip_address": null,
    "created_at": "2023-07-01T14:00:00Z",
    "actor_name": "Zendesk"
}
```

## Related Articles

- [Zendesk Audit Logs - Overview](https://developer.zendesk.com/api-reference/ticketing/account-configuration/audit_logs/)
- [Supported Authentication Types in Zendesk](https://developer.zendesk.com/api-reference/introduction/security-and-auth/)