Hugging Face Audit Logs

The Hugging Face Hub audit log records user and system actions across your organization, including repository management, membership and access control changes, SSO and OAuth events, billing changes, and Spaces and Jobs activity. These logs help security and compliance teams maintain audit trails, monitor administrative activity, and build detections on access to your Hugging Face resources.

Setup

Hugging Face supports API polling to collect audit log events from your organization via the audit-log export endpoint (GET /api/organizations/{name}/audit-log/export).

1. Go to Sources in RunReveal
2. Click the Hugging Face source tile
3. Give it a name
4. Fill in your Organization name and an Access Token
5. Click Connect Source

Access Token Configuration

Prerequisites:

• Your organization must be on a Team or Enterprise plan. Audit logs are not available on free plans.
• The token must belong to an organization admin. A read/write org membership is not enough — Hugging Face only exposes audit logs to admins.
• Use the organization name (slug), not the display name — for example my-org from huggingface.co/my-org.

Which token type to use:

A classic Read token means the token itself is read-scoped — it does not mean a read-only org member can export audit logs. The user who creates the token must still be an org admin.

Team and Enterprise orgs can also enforce token management policies:

Creating a classic Read token:

1. Sign in to huggingface.co as an organization admin
2. Open Settings → Access Tokens
3. Click Create new token, choose Read, and give it a name
4. Copy the token — it will only be displayed once

Creating a fine-grained token:

1. Sign in as an organization admin
2. Open Settings → Access Tokens (or use a preset such as read-only)
3. Click Create new token and choose Fine-grained
4. Name the token (for example runreveal-audit-logs)
5. Attach your organization under resource access
6. Use a Read-Only preset, or Custom with the org scopes you need
7. Create the token and copy it once — it will not be shown again

If the org requires administrator approval, tokens created by an org admin for that org are auto-approved. Non-admin tokens stay pending until an admin approves them.

Collected Events

Hugging Face audit events follow a scope.action naming convention. RunReveal stores the event type in the eventName field. Scopes include:

• org — membership, roles, invitations, SSO login/join, settings, token approval, and security configuration changes (e.g. org.add_user, org.remove_user, org.sso_login, org.update_settings)
• repo — repository lifecycle, secrets and variables, settings, and trusted publishers (e.g. repo.create, repo.delete, repo.move, repo.update_settings)
• collection — collection create and delete events
• spaces — storage, volumes, hardware, and sleep-time changes
• resource_group — resource group lifecycle and membership changes
• jobs / scheduled_job — job creation, cancellation, and schedule changes
• billing — subscription, payment method, and marketplace changes
• oauth — OAuth token activity

Event Data Structure

Each audit event includes:

• Event ID and Type — Unique identifier (_id) and event type (type)
• Timestamp — When the action occurred (createdAt, RFC 3339)
• Actor Information — Author username, ID, and type
• Network Context — Source IP address and resolved location (country, city)
• Token Context — When applicable, the token type, role, and last 4 characters used for the action

Data Collection

• Collection Method: API polling every 5 minutes
• Backfill: On first connection RunReveal ingests all available audit history (the export returns up to the last 100,000 events)
• Event Format: JSON with normalized fields for consistent querying

Verify It's Working

Once added the source logs should begin flowing within a minute.

You can validate we are receiving your logs by running the following SQL query.

SELECT * FROM runreveal.logs WHERE sourceType = 'huggingface' LIMIT 1

Schema

The following columns are exposed for this source. RunReveal applies schema normalization across all sources, ensuring uniform field names and data types for cross-source queries and reusable detection logic.

Troubleshooting

Authorization error / HTTP 403 on audit-log export

RunReveal polls GET /api/organizations/{name}/audit-log/export. When Hugging Face rejects the request, source logs look like:

huggingface audit-log export request failed: failed to parse response (HTTP 403 from GET https://huggingface.co/api/organizations/<org>/audit-log/export): json: cannot unmarshal object into Go value of type []json.RawMessage; body: {"error":"Authorization error."}

The important part is HTTP 403 with {"error":"Authorization error."}. The cannot unmarshal object... text is a follow-on parse failure: Hugging Face returned an error object instead of the expected JSON array of events.

Common causes:

1. Token owner is not an org admin — Membership with read or write is not enough. Create the token while signed in as an admin of that organization.
2. Organization is not on Team or Enterprise — Audit-log export is a Team & Enterprise feature.
3. Org token policy blocks classic tokens — If the org requires fine-grained tokens only, classic Read/Write tokens return 403. Create a fine-grained token scoped to the organization instead.
4. Fine-grained token pending, denied, or revoked — Under approval policies, pending/denied tokens get 403. Enterprise orgs can also revoke tokens. Check the token status under Settings → Access Tokens, or ask an org admin to approve it.
5. Wrong or expired token — Regenerate the token and update the Access Token on the RunReveal source.
6. Wrong organization slug — Use the org name in the Hub URL (huggingface.co/<org>), not the display name.

Verify outside RunReveal:

curl -sS -i -H "Authorization: Bearer YOUR_TOKEN" \
  "https://huggingface.co/api/organizations/YOUR_ORG/audit-log/export" | head

• HTTP 200 with a JSON array — the token works; update the same token and org name on the RunReveal source.
• HTTP 403 with {"error":"Authorization error."} — fix plan, admin role, or org token policy before retrying in RunReveal.

Org admins can review and change token policy under Hugging Face Tokens Management (docs).

Helpful Links

• Hugging Face Audit Logs - Overview of the organization audit log and available event types
• Hugging Face Hub API - Hub REST API reference
• Access Tokens - Creating and managing access tokens
• Tokens Management - Org token policies (fine-grained only, admin approval)