# Audit Logs

Collects audit log events from Cloudsmith organizations capturing administrative actions, security events, and package repository activities.

**Sync Type: Incremental**

## Requirements

Before connecting Monad to Cloudsmith, you need:

1. **Cloudsmith Organization Slug**
   - Your unique organization identifier
   - Format: lowercase-with-hyphens (e.g., `my-org`)
   - Found in your Cloudsmith organization URL: `https://cloudsmith.io/org/{organization-slug}/`

2. **Cloudsmith API Key**
   - Must have audit log read access
   - Can be generated from your user account settings
   - Instructions: [Creating API Keys in Cloudsmith](https://help.cloudsmith.io/reference/authentication#api-key-authentication)

### Creating a Cloudsmith API Key

1. Log in to your Cloudsmith account
2. Navigate to **Account Settings** > **API**
3. Click **Create API Key** or find your existing API key
4. Copy the generated API key and store it securely
5. Verify you can access audit logs for your organization

**Important**: API keys provide access to your organization's audit logs. Store them securely and never commit them to version control

## Configuration

The following configuration defines the input parameters. Each field's specifications, such as type, requirements, and descriptions, are detailed below.

#### Settings

| Setting             | Type   | Required | Description                                                                                                                                                                                            |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Organization        | string | Yes      | The Cloudsmith organization slug (e.g., `my-org`). Found in your Cloudsmith organization URL.                                                                                                          |
| Backfill Start Time | string | No | The date to start fetching data from. If not specified, no past records will be fetched. |
| 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. |

#### Secrets

| Secret  | Type   | Required | Description                                                                                                     |
| ------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| API Key | string | Yes      | Cloudsmith API key used to authenticate requests via the X-Api-Key header. Found in your user account settings. |

## Troubleshooting

### Common Issues

#### 1. Authentication Failures (401 Unauthorized)

**Symptoms**: Error message indicating unauthorized access

**Causes**:

- Invalid or expired API key
- API key has been revoked
- Incorrect API key format

**Solutions**:

- Verify the API key is correct and properly copied
- Check that the API key hasn't been revoked in Cloudsmith
- Generate a new API key if necessary
- Ensure no extra whitespace in the API key value

#### 2. Organization Not Found (404 Not Found)

**Symptoms**: Error message indicating resource not found

**Causes**:

- Incorrect organization slug format
- Organization slug contains typos
- Organization has been deleted or archived

**Solutions**:

- Verify the organization slug format: lowercase with hyphens (e.g., `my-org`)
- Check the slug matches your Cloudsmith organization URL
- Confirm the organization exists and is active
- Ensure you have access to the organization

#### 3. Rate Limit Exceeded (429 Too Many Requests)

**Symptoms**: Temporary failures with rate limit messages

**Causes**:

- Exceeded 1,000 requests per minute limit
- Multiple connectors using the same API key

**Solutions**:

- The connector automatically retries with exponential backoff
- The connector implements automatic rate limiting (1 request per second)
- Consider using separate API keys for different connectors
- Wait for the rate limit window to reset (1 minute)

#### 4. No Data Appearing

**Symptoms**: Connector runs successfully but no audit logs are collected

**Causes**:

- `backfill_start_time` set too far in the past (outside retention period)
- No audit events occurred during the specified timeframe
- API key lacks audit log read access

**Solutions**:

- Verify audit events exist in Cloudsmith for the specified time range
- Check `backfill_start_time` is within your organization's audit log retention period
- Verify the API key has access to audit logs
- Contact Cloudsmith support if audit logging appears disabled

#### 5. Invalid Backfill Start Time

**Symptoms**: Validation error about backfill time format

**Causes**:

- Backfill time not in RFC3339 format
- Using invalid date/time values
- Timestamp in the future

**Solutions**:

- Use RFC3339 format: `2024-01-01T00:00:00Z`
- Include timezone (Z for UTC or offset like +05:00)
- Verify the date is valid and not in the future
- Confirm the date is within your audit log retention period

## Related Articles

- [Cloudsmith API Documentation](https://help.cloudsmith.io/reference/introduction)
- [Cloudsmith API Authentication](https://help.cloudsmith.io/reference/authentication)
- [Cloudsmith Audit Logs](https://help.cloudsmith.io/reference/audit_log_namespace_list)

## Sample Record

```json
{
  "actor": "john.doe",
  "actor_ip_address": "203.0.113.42",
  "actor_kind": "user",
  "actor_location": {
    "city": "San Francisco",
    "country": "United States",
    "country_code": "US",
    "latitude": "37.7749",
    "longitude": "-122.4194"
  },
  "actor_slug_perm": "550e8400-e29b-41d4-a716-446655440000",
  "actor_url": "https://api.cloudsmith.io/users/550e8400-e29b-41d4-a716-446655440000/",
  "context": "Repository",
  "event": "Repository.Create",
  "event_at": "2024-02-12T10:30:45Z",
  "object": "my-repo",
  "object_kind": "Repository",
  "object_slug_perm": "660e8400-e29b-41d4-a716-446655440001",
  "target": "my-org",
  "target_kind": "Organization",
  "uuid": "770e8400-e29b-41d4-a716-446655440002"
}
```