Audit Logs - Unkey

Audit logs capture every mutation in your Unkey workspace — key creation, permission changes, revocations, rate limit updates, and more. They’re essential for security investigations, compliance requirements, and understanding who changed what and when.

Why Audit Logs Matter

Security investigations

When something goes wrong, trace exactly what happened, when, and who was responsible.

Compliance requirements

SOC 2, HIPAA, GDPR, and other frameworks require audit trails for sensitive operations.

Team visibility

Know when team members create, modify, or revoke keys — especially critical in shared workspaces.

Debugging

Figure out why a key stopped working, when a permission was changed, or who updated configuration.

What Gets Logged

Unkey automatically logs every mutation operation. Read operations are not logged — only actions that create, update, or delete resources.

Logged Events by Category

Event	Description
`key.create`	A new API key is created
`key.update`	Key properties are modified (name, metadata, limits, etc.)
`key.delete`	A key is permanently deleted
`key.reroll`	A key is replaced with a new value while preserving config

Event	Description
`api.create`	A new API container is created
`api.update`	API settings are modified
`api.delete`	An API is deleted

Event	Description
`identity.create`	A new identity is created
`identity.update`	Identity metadata or rate limits are updated
`identity.delete`	An identity is deleted

Event	Description
`role.create`	A new role is created
`role.update`	Role properties are modified
`role.delete`	A role is deleted
`permission.create`	A new permission is created
`permission.update`	Permission properties are modified
`permission.delete`	A permission is deleted
`authorization.connect_role_and_permission`	A permission is added to a role
`authorization.disconnect_role_and_permission`	A permission is removed from a role
`authorization.connect_role_and_key`	A role is assigned to a key
`authorization.disconnect_role_and_key`	A role is removed from a key
`authorization.connect_permission_and_key`	A permission is assigned directly to a key
`authorization.disconnect_permission_and_key`	A permission is removed from a key

Event	Description
`ratelimitNamespace.create`	A rate limit namespace is created
`ratelimitNamespace.update`	Namespace settings are updated
`ratelimitNamespace.delete`	A namespace is deleted
`ratelimit.create`	A rate limit configuration is created
`ratelimit.update`	Rate limit settings are modified
`ratelimit.delete`	A rate limit is removed
`ratelimit.set_override`	A custom override is set for an identifier
`ratelimit.delete_override`	An override is removed

Event	Description
`workspace.create`	A new workspace is created
`workspace.update`	Workspace settings are changed
`workspace.delete`	A workspace is deleted
`workspace.opt_in`	A feature flag is enabled

Event	Description
`webhook.create`	A webhook endpoint is created
`webhook.update`	Webhook configuration is updated
`webhook.delete`	A webhook is deleted

Verification events (key.verify) are tracked in Analytics, not audit logs. Audit logs focus on configuration changes, not runtime operations.

Accessing Audit Logs

Dashboard

Navigate to Audit Logs

Sign into app.unkey.com and click Audit Logs in the sidebar

Browse events

See a chronological list of all workspace mutations

Click for details

Click any row to see complete request/response payloads and metadata

Log Entry Details

Each audit log entry contains:

Field	Description
Time	Precise timestamp when the change occurred (ISO 8601 format)
Actor	Who made the change — a user (via dashboard) or root key (via API)
Action	The operation type: `Create`, `Update`, `Delete`, etc.
Event	What was affected: `key`, `permission`, `api`, `identity`, etc.
Resource ID	The ID of the affected resource (key ID, API ID, etc.)
Description	Human-readable summary of the change
Request	Full request payload (what was sent)
Response	Full response payload (what was returned)
Metadata	Additional context (IP address, user agent, etc.)

Filtering Audit Logs

Use filters at the top of the audit log page to narrow down results:

By Event Type
By Actor
By Time Range
By Resource

Filter by specific event categories:

Keys: Only key-related events
Permissions: Authorization changes
Rate Limits: Rate limit configuration
Workspace: Workspace-level changes

Useful for tracking specific types of changes.

Common Use Cases

Security incident investigation

Scenario: A key was compromised and you need to understand the blast radius.

Find when the key was created

Filter logs by key.create and search for the key ID

Check if it was modified

Look for key.update events — was it given extra permissions?

See who had access

Check the actor field — was it created via API or dashboard?

Verify revocation

Confirm key.delete or key.update (enabled=false) event exists

Export evidence: Click “Export” to download logs for security reports.

Compliance auditing

Scenario: Annual SOC 2 audit requires proof of access controls.Generate reports showing:

All permission changes in the audit period
Who granted/revoked access
When keys were created/deleted
Rate limit policy changes

Permission Changes
Key Lifecycle

Filter by:

permission.create
permission.delete
authorization.*

Export as CSV for auditor review.

Filter by:

key.create
key.delete

Show complete key lifecycle documentation.

Debugging configuration issues

Scenario: A key suddenly stopped working and the user claims they didn’t change anything.

Search for the key ID

Filter audit logs by resource ID

Look for recent changes

Check for key.update events in the past 7 days

Identify the change

Common culprits:

enabled set to false
expires timestamp in the past
Rate limit reduced to 0
Permission removed

Check who made the change

Was it a team member, API call, or automated process?

Team activity monitoring

Scenario: You want to see what your team has been doing this week.Filter by:

Time range: Last 7 days
Actor: Each team member

Useful for:

Onboarding review (did new hire create test keys?)
Activity verification (is contractor still making changes?)
Change management (what changed during the deployment?)

Automated system changes

Scenario: Track changes made by automated systems or CI/CD.Filter by:

Actor: Specific root key ID used by automation

Monitor:

Are automated deploys creating/updating keys correctly?
Did the migration script run successfully?
Are rate limits being set programmatically as expected?

Log Retention

Audit logs are retained based on your plan:

Plan	Retention Period	Export
Free	7 days	✓
Pro	90 days	✓
Enterprise	Custom (up to unlimited)	✓ with custom formats

After the retention period, logs are permanently deleted and cannot be recovered. Export logs regularly if you need longer retention.

Exporting Logs

Dashboard Export
API Export (Enterprise)
Continuous Export (Enterprise)

Apply desired filters
Click Export button
Choose format: CSV or JSON
Download begins automatically

Exports include all filtered events with complete payloads.

// Query audit logs programmatically
const response = await fetch("https://api.unkey.com/v1/auditlog.list", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.UNKEY_ROOT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    workspaceId: "ws_...",
    start: Date.now() - 30 * 24 * 60 * 60 * 1000,
    end: Date.now(),
    eventType: "key.*"
  })
});

const logs = await response.json();

Best Practices

Review logs regularly

Check audit logs weekly for unusual activity:

Unexpected deletions
Permission escalations
Bulk changes
Off-hours modifications

Use root keys sparingly

Root keys have full workspace access. Create narrow-scoped root keys for automation:

// Good: Limited scope
permissions: ["key.create", "key.update"]

// Bad: Full access
permissions: ["*"]

Export for compliance

If you need logs older than your retention period:

Set up automated monthly exports
Store in S3 or compliance vault
Include in annual audit packages

Name root keys descriptively

When creating root keys, use clear names:

CI/CD Production Deploy
Stripe Webhook Handler
Analytics Export Script

Makes audit logs much easier to understand.

Monitor for bulk changes

Set up alerts for:

10 keys deleted in 1 hour
50 keys created in 1 hour
Mass permission changes

Could indicate compromise or runaway script.

Document procedures

Create runbooks for:

How to investigate security incidents
Where to find specific log types
Export procedures for auditors
Retention policy documentation

Audit Log vs Analytics

Understand the difference:

Feature	Audit Logs	Analytics
Purpose	Track configuration changes	Track runtime usage
Events	Create, update, delete	Key verifications
Volume	Low (only mutations)	High (every API call)
Retention	7-90+ days	7-90+ days
Use for	Security, compliance, debugging	Usage patterns, billing, optimization

Both are important:

Audit logs answer “who changed what?”
Analytics answer “how is it being used?”

Security Considerations

Audit logs are immutable

Once created, audit log entries cannot be modified or deleted by users. This ensures integrity for compliance and security investigations.

Actor attribution

Every change is attributed to:

User: Dashboard changes show user email
Root key: API changes show root key ID and name

Never share root keys between systems — create separate keys for accurate attribution.

Request/response payloads

Full payloads are captured, which may include:

Key values (only on creation)
Metadata
Configuration

Never put secrets in metadata or key names.

Data privacy

For GDPR/CCPA compliance:

Don’t store PII in key names or metadata
Request deletion via [email protected]
Logs for deleted resources remain (shows deletion event)

Enterprise Features

Enterprise plans include advanced audit log capabilities. Contact us to learn more.

Extended retention

Keep logs for years, not days:

1 year standard
Multi-year available
Unlimited retention for regulated industries

SIEM integration

Stream logs to security tools:

Datadog
Splunk
Sumo Logic
Custom webhooks

Advanced filtering

More powerful queries:

Regex search
Complex boolean logic
Custom field matching
SQL-like queries

Compliance reports

Automated report generation:

SOC 2 evidence
HIPAA audit trails
Custom compliance formats
Scheduled exports

Next Steps

Analytics

Track key usage and verification patterns

Security Overview

Learn how Unkey protects your data

Root Keys

Create and manage root keys for API access

API Reference

Complete API documentation

Get Started

Core Features

Integration Guides

Advanced Topics

Security

Platform

​Why Audit Logs Matter

Security investigations

Compliance requirements

Team visibility

Debugging

​What Gets Logged

​Logged Events by Category

​Accessing Audit Logs

​Dashboard

​Log Entry Details

​Filtering Audit Logs

​Common Use Cases

​Log Retention

​Exporting Logs

​Best Practices

Review logs regularly

Use root keys sparingly

Export for compliance

Name root keys descriptively

Monitor for bulk changes

Document procedures

​Audit Log vs Analytics

​Security Considerations

​Enterprise Features

Extended retention

SIEM integration

Advanced filtering

Compliance reports

​Next Steps

Analytics

Security Overview

Root Keys

API Reference

Build docs developers (and LLMs) love

Why Audit Logs Matter

What Gets Logged

Logged Events by Category

Accessing Audit Logs

Dashboard

Log Entry Details

Filtering Audit Logs

Common Use Cases

Log Retention

Exporting Logs

Best Practices

Audit Log vs Analytics

Security Considerations

Enterprise Features

Next Steps