# Audit Events

Ingests audit events from Apple Business, capturing administrative and security-relevant actions such as device, account, configuration, subscription, and API-key changes.

**Sync Type: Incremental**

## Prerequisites

Before configuring this input, you need:

1. **An Apple Business account** with the **Administrator** role (or another role with permission to manage API accounts), since creating an API account requires elevated privileges.
2. **An API account created in Apple Business** under **Preferences > API**, along with its downloaded private key. See [Authentication](#authentication) below for the exact steps — the private key can only be downloaded once, at the moment the API account is created.

## Authentication

This input uses **OAuth 2.0 client-credentials grant with a private-key-signed (ES256) JWT client assertion** — Apple's standard authentication method for the Business API. Rather than a static API key, Monad signs a short-lived JWT with your EC (P-256) private key and exchanges it for an access token at Apple's token endpoint (`https://account.apple.com/auth/oauth2/token`, scope `business.api`). Monad handles minting the assertion and refreshing the access token automatically — you only need to supply the three values below.

To create the credentials:

1. Sign in to [Apple Business](https://business.apple.com) with an account that has permission to manage API accounts.
2. Go to **Preferences > API**.
3. Click **Create API Account**, give it a descriptive name (for example, `Monad`), and assign it a role with read access to audit events.
4. When the API account is created, Apple generates and displays an EC (P-256) private key. **Download it immediately** — Apple does not store a copy, and it cannot be retrieved again after you leave the page. If you lose it, you'll need to create a new API account and key.
5. Record the **Client ID** (formatted `BUSINESSAPI.<uuid>`) and **Key ID** shown alongside the API account. You'll need these two values, along with the private key, to configure the input.

## Configuration

### Settings

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| Backfill Start Time | string | No | Date to start fetching audit events from (ISO 8601). If not specified, only events created after the input first runs are fetched. |
| Use Synthetic Data | boolean | No | Generate synthetic demo data instead of connecting to the real data source. Useful for testing pipelines before go-live. |

### Secrets

| Secret | Type | Required | Description |
|--------|------|----------|-------------|
| Client ID | string | Yes | Client ID of the Apple Business API account, formatted `BUSINESSAPI.<uuid>`. |
| Key ID | string | Yes | Key ID assigned to the private key when it was created in Apple Business. |
| Private Key | string | Yes | EC (P-256) private key issued by Apple Business, as an unencrypted PEM (PKCS#8 or SEC1). Downloadable only once, at API-account creation. |

## Setup Walk-through

1. In Apple Business, create an API account under **Preferences > API** and download its private key (see [Authentication](#authentication) above).
2. In Monad, navigate to **Inputs** and click **Add Input**.
3. Search for **Apple Business** and select **Audit Events**.
4. Enter the **Client ID**, **Key ID**, and **Private Key** from step 1.
5. Optionally, set **Backfill Start Time** to ingest historical audit events from a specific date.
6. Click **Save** and verify that the input status transitions to **Running**.

## Troubleshooting

### Common Issues

**Authentication failures**
- Confirm the Client ID and Key ID match exactly what's shown for the API account in **Preferences > API** — a mismatch between the Key ID and the private key will cause the signed JWT to be rejected.
- Ensure the private key was pasted in full, including the `-----BEGIN` / `-----END` header and footer lines, and that it's an unencrypted PEM (PKCS#8 or SEC1).
- If the private key was lost after the one-time download, you'll need to create a new API account in Apple Business and reconfigure the input with the new credentials.

**No events returned**
- If you set a **Backfill Start Time**, confirm it isn't in the future.
- Confirm the API account's role has permission to read audit events.
- New API accounts only have audit events from the point they were created onward, plus whatever window Apple retains — see Apple's documentation for retention details.

**Rate limiting**
- Apple does not publish a documented rate limit for this API. Monad applies a conservative default outbound request rate; if you see persistent throttling, contact Apple Business Manager support.

## Related Articles

- [Apple Business API Documentation](https://developer.apple.com/documentation/applebusinessapi)
- [Apple Business Audit Events API](https://developer.apple.com/documentation/applebusinessapi/get-audit-events)