LiteLLM audit logs

The LiteLLM audit trail records four action types: create, update, delete and regenerate. These apply to four object types: keys, teams, users and models. Each entry carries an actor field that names who performed the change. This field is the main reason to keep the trail, so a reviewer should confirm early that it holds an individual's identity and not a generic value. Audit logs require an Enterprise license. With Enterprise they are on by default, but your team should set store_audit_logs in litellm_settings, or the LITELLM_STORE_AUDIT_LOGS variable, so the setting is explicit in your configuration and can be checked during review.

Request-level traffic is not the audit trail. The records of each prompt, response, model call and token count belong to request and spend logging, which is covered separately. Those records show what a virtual key did with the gateway. They do not show who created the key, who raised its budget, or who regenerated its secret. A reviewer who accepts request logs as evidence of administrative change will miss the questions that matter most. Ask the team to show, for one key, the request log and the audit entry side by side, and to confirm that each answers a different question.

Read-only access may not be recorded. Listing keys, opening team settings, or viewing a model's configuration may leave no entry in the audit trail. If your policy requires evidence of who viewed credentials, budgets or model definitions, this gap needs a documented decision. Test the read actions in the admin UI and the API during the non-production run, record what appears, and decide whether to accept the gap, restrict admin access further, or add a separate control. Do not assume that a missing entry means the view did not happen.

Changes made with the master key, or with UI_USERNAME and UI_PASSWORD, show only the shared admin identity. Anyone holding those values signs in as proxy admin, so the audit trail cannot tell the people apart. Limit these credentials to documented break-glass use, keep the master key in a secret manager, and put individual sign-in in front of the admin UI. Single sign-on is what makes the actor field meaningful for day-to-day administration, and it should be in place before the audit trail is relied on for accountability.

Before relying on the trail, test each action type against each object type that supports it in a non-production gateway. For each test, confirm the actor value, the object identifier, the timestamp and any before and after details the product captures. If you export to S3 with audit_log_callbacks set to s3_v2, confirm that JSON files appear under audit_logs/ with a date folder and that the same fields survive the export. Keep the test record as evidence of what the trail captures, and ask your LiteLLM contact to confirm any field you cannot verify in your own environment.

Audit logs only help when each entry names a person. The LiteLLM audit log records who created, updated, deleted or regenerated keys, teams, users and models, but the Admin UI also accepts UI_USERNAME and UI_PASSWORD, or the master key. Anyone who holds those values signs in as proxy admin, so an entry shows that an admin acted, not which engineer did it. Until admins stop sharing these credentials, the log cannot separate one person from another, and no export setting changes that.

LiteLLM's admin UI supports SSO with Google, Microsoft Entra ID (Azure AD), Okta and generic OIDC providers. From v1.76.0, SSO is free for up to 5 users, and an Enterprise license is needed beyond that. Count the people who will administer keys, teams, users and models before choosing a path, because that number decides whether the free tier is enough. Also confirm with your identity provider and LiteLLM which group or role claims map to admin rights. SCIM provisioning and JWT authentication are Enterprise features, so confirm with your vendor whether your identity provider needs either one before you commit to a design.

The order of work matters. First, issue a personal SSO identity to every person who administers the gateway. Second, move those admins to SSO sign-in and make a test change, such as creating and then deleting a test team, to confirm that the audit entry shows the person's identity. Third, rotate or restrict the shared values. Change UI_PASSWORD, limit who can read the master key in your secret manager, and document a break-glass procedure for the rare case when SSO is unavailable. Skipping the second step is the most common way to end up with a log that looks complete but names no one.

Plan for the actions SSO does not cover. Automation, CI jobs and scripts that call the proxy with the master key will still appear as proxy admin, so give each one its own virtual key or service identity before you retire the shared credentials. Ask your vendor to confirm how the admin UI session and API key actions are recorded in the audit entry for your release, and check that exported files under audit_logs/ carry the actor field you expect. Record the result of the test change as evidence, so the sign-off can show the log identifies individuals.

The audit export runs asynchronously, so it writes beside the gateway rather than inside the request path. Audit logs require an Enterprise license, so confirm your license before you configure the export. Then set audit_log_callbacks to s3_v2 in the proxy configuration. The gateway writes JSON files under audit_logs/ in your bucket, with one folder per day named YYYY-MM-DD. Before go-live, ask your LiteLLM contact to confirm, for your release, the callback name, the folder layout, the file format and the exact field names for the acting user, action, target type, target ID and timestamp. Record those names in a data dictionary that your SIEM or data platform team owns. Test with one create and one regenerate action on a non-production key, then find both events in the bucket before you rely on the pipeline.

The gateway's storage permissions should be narrow. It needs to write objects under the audit_logs/ prefix and nothing else in the bucket. Ask your vendor whether it needs any other S3 action, because each extra permission on the gateway role increases what a compromised proxy could reach. If your retention policy requires that events cannot be altered or deleted, decide whether to use bucket versioning, object lock or both, and confirm the gateway's role is compatible with that setting. Block public access, encrypt objects with a key your security team controls, and turn on access logging or data event logging so you can see who reads the bucket. Keep audit data in a dedicated bucket or a dedicated prefix that application data cannot write to.

Split the write and read roles from the start. The gateway's write role is assumed by the proxy workload and holds only the put permission on the audit prefix. The reviewer read role is assumed by a named security or compliance group through your identity provider, with multi-factor authentication required and session logging on. Reviewers need list and get permissions on the audit prefix and no ability to change the gateway, its configuration or its keys, because the gateway is the system being audited. Nobody on the platform team should hold both roles. Review membership of both roles at a fixed interval, and remove access for people who change teams. Document who may approve a change to either role, so a platform engineer cannot quietly widen the reviewer's access.

Reading the files usually means a scheduled ingestion job in your SIEM or data platform. The job loads each JSON file, uses the date folder as a partition, and normalizes timestamps to UTC. The identity step matters most. Join the acting-user field to identity records exported from your identity provider, so each action resolves to a person, their team and their role at the time. Without single sign-on, the actor often resolves to a shared credential. LiteLLM's Moving from OSS checklist warns that anyone who signs in with the UI username and password or the master key appears as proxy admin, and the audit trail cannot identify them. Run the join only after SSO is in place, test it with a known change, and repeat the test after each upgrade, since field names can change between releases.