> ## Documentation Index > Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Audit export > Send Ryvn API audit logs to your organization's S3 or GCS bucket Connect a bucket you own to receive Ryvn API audit logs for your organization. Each organization has one audit export connection to an S3 or GCS bucket. These records describe covered Ryvn API requests, not Kubernetes or cloud-provider activity. For those logs, see [infrastructure auditing](/docs/guides/infrastructure-auditing). Audit capture is best effort; this is not a complete record of every endpoint, authentication failure or malformed request. ## Before you begin * You need permission to manage integrations in Ryvn. Read access lets you inspect the connection; write access is required to create, test or delete it. * Have an existing bucket and credentials that can apply the generated permissions. Ryvn does not create the bucket. * **S3:** have the bucket's region and an ARN for a **new, dedicated customer IAM role**. Use credentials that can create the role and attach its policy. The setup script creates that role; it does not adopt or overwrite an existing role. If you use an S3 KMS key, also have its key ARN. * **GCS:** the bucket must use uniform bucket-level access. Use credentials that can update its IAM policy. To enable audit export, create the connection, apply the setup script and successfully test access. If the service is unavailable, contact [Ryvn support](/docs/support/contact-us). Choose a short prefix such as `audit/`. Each slash-separated segment must be nonempty and contain only ASCII letters, digits, `.`, `_` or `-`; `.` and `..` cannot be entire segments. End the prefix with `/`. The maximum is 900 ASCII characters, but the backend may require a shorter prefix to leave room for the rest of each object key. ## Configure the connection **1. Create the connection** **Dashboard** Open **Settings > Connections > Audit export**. Enter the **Bucket** and **Prefix**. The supported provider is selected automatically. For S3, also enter **Region**, **Customer role ARN** and, if needed, **KMS key ARN**. Click **Create connection**. **CLI** [Authenticate the CLI](/docs/cli#authenticate), then create the connection in your current organization. For S3: ```bash theme={null} ryvn create connection --type audit-export --provider s3 \ --bucket example-audit --prefix audit/ --region us-east-1 \ --customer-role-arn arn:aws:iam::123456789012:role/ryvn-audit-export ``` Add `--kms-key-arn` if needed. For GCS: ```bash theme={null} ryvn create connection --type audit-export --provider gcs \ --bucket example-audit --prefix audit/ ``` Replace the example bucket and role with your own. The audit export connection takes no positional name; select it with `--type audit-export`. Creating the connection sets up Ryvn's managed identity and access grants. It does not test bucket access or enable export. Apply the returned setup next, then test access to enable audit export; no access test runs automatically. **2. Apply the setup** **Dashboard** Review **Setup script**, then use **Copy** to paste it into your cloud shell, or **Download** to save it. The displayed text exactly matches Copy, including its quoted shell wrapper. Download saves the raw script returned by Ryvn without the wrapper. Sign in to the bucket's account or project with permission to apply the changes. For a downloaded file, run `sh ryvn-audit-export-setup.sh` after reviewing it. **CLI** Use `ryvn describe connection --type audit-export` to inspect the connection and setup. Save just the script with `--setup-script`: ```bash theme={null} ryvn describe connection --type audit-export --setup-script > ryvn-audit-export-setup.sh ``` Review the file, then run it with credentials for the bucket's account or project: ```bash theme={null} sh ryvn-audit-export-setup.sh ``` If setup is missing, stop and contact [Ryvn support](/docs/support/contact-us). Reading the connection or its setup does not change cloud access. For S3, the script creates the dedicated customer role and grants writes under your prefix. It stops if that role already exists. For GCS, it grants your organization's Ryvn service account access under the prefix and requires uniform bucket-level access. For encrypted buckets, follow the returned setup and its key-policy requirements rather than granting broader permissions. **3. Test access** **Dashboard** Return to the connection and click **Test access**. **CLI** ```bash theme={null} ryvn test connection --type audit-export ryvn describe connection --type audit-export ``` The test writes a unique object under `.ryvn-probe/`. It leaves the object in your bucket for you to remove. A successful test enables audit export for your organization; it does not confirm that audit records have arrived. Check status and your bucket separately. ## Status and troubleshooting Use **Refresh** on the connection page or `ryvn describe connection --type audit-export` to read the latest returned status. Add `-o json` for structured output. The dashboard and CLI show the returned status and **Reason** without inferring success from activity or a successful access test. | Returned status | What to do | | - | - | | `unknown` | There is not enough evidence to report delivery health. Do not read it as healthy or as no activity. | | `blocked` | Read **Reason** and resolve the reported access, configuration or delivery problem. Apply setup and retest if access failed. | | `unavailable` | Contact Ryvn support. Check **Integration available** and **Worker available**; a bucket permission change alone will not make the service available for audit export delivery. | Other returned values are shown as received. **Processed through (exclusive)** is a historical processing boundary: it excludes the timestamp shown and may come from a previous destination. It does not prove that every event reached the current bucket. **Expired interval start/end** bound gaps in retained history; they do not mean every moment between them is missing or give an event-loss count. Delivery health is not currently reported for this connection. A successful access test confirms write access. To check delivery, look for exported `.jsonl.gz` files under your configured bucket prefix. If expected records are missing, contact Ryvn support. If an access test fails, read **Reason** and the test error, check the bucket, prefix and generated permissions, and allow IAM changes to propagate before retrying. For S3, confirm the region, new dedicated role and any KMS requirements in the setup. For GCS, confirm uniform bucket-level access and the exact service account shown in setup. If a prefix is rejected for object-key length, use a shorter prefix. Exports are limited to the applicable log-retention period; outages do not extend it. Capture can miss records before export. Exports are gzip-compressed JSON Lines (`.jsonl.gz`) under your configured prefix, with one `audit_log.v1` record per line. Duplicate records are possible; deduplicate by `eventId`. You control retention and processing after delivery to your bucket. ## Export object layout Objects use this key layout under your configured prefix: ```text theme={null} /--/.jsonl.gz ``` For example: ```text theme={null} audit/org-123/2026-10-15T12:00:00.000000000Z--2026-10-15T13:00:00.123456789Z/550e8400-e29b-41d4-a716-446655440000.jsonl.gz ``` Timestamps are UTC with exactly nine fractional digits. The interval is the actual source-read window, inclusive of its start and exclusive of its end, not the first and last event timestamps in the file. Multiple objects can cover the same or overlapping time windows, and records can appear in more than one object. Deduplicate by `eventId` when processing files. ## Replace or delete the connection Deleting the connection disables audit export for your organization. Changing the bucket, prefix or other destination settings requires deleting and recreating the connection. Changing destinations keeps saved export progress; it does not restart the full history in the new bucket. Some recent records may be repeated. **Dashboard** Click **Delete connection**, then **Confirm delete**. To replace it, create the new connection, apply its setup and test access again. **CLI** ```bash theme={null} ryvn delete connection --type audit-export ``` To replace it, repeat the create, setup and test steps with the new destination. For S3, deletion removes the connection and its connection-specific Ryvn-side grant. Your bucket, customer role, policies, data and shared organization identity remain. If Ryvn cannot finish grant cleanup, it keeps the configuration so you can retry deletion. For GCS, deletion removes the Ryvn configuration but does not revoke the customer-managed bucket binding. Remove the relevant binding separately if no longer needed; do not remove the shared organization identity. Your bucket and existing objects remain.