Audit Log Endpoints

Audit logs provide an immutable, time-series record of every action performed within your VeraID organization. Logs are stored in TimescaleDB hypertables with automatic time-based partitioning for efficient querying across large time ranges.

Audit Log Fields

Every audit log entry contains the following fields:

Field	Type	Description
id	string	Unique identifier for the log entry
actorType	string	Type of actor: USER, IDENTITY, SYSTEM
actorId	string	Identifier of the actor
actorName	string	Display name of the actor
action	string	The action that was performed
resourceType	string	Type of resource affected (e.g., identity, credential, policy)
resourceId	string	Identifier of the affected resource
outcome	string	Result of the action: SUCCESS, FAILURE, DENIED
ipAddress	string	Source IP address of the request
userAgent	string	User agent string of the client
metadata	object	Additional context specific to the action
timestamp	string	ISO 8601 timestamp of when the action occurred

---

Query Audit Logs

Retrieve audit logs with filters for actor, action, resource, outcome, and time range.

GET /api/v1/audit-logs

Query Parameters

Parameter	Type	Description
actorType	string	Filter by actor type: USER, IDENTITY, SYSTEM
actorId	string	Filter by specific actor ID
action	string	Filter by action (e.g., identity.created, credential.used)
resourceType	string	Filter by resource type (e.g., identity, credential, policy)
outcome	string	Filter by outcome: SUCCESS, FAILURE, DENIED
startDate	string	Start of time range (ISO 8601)
endDate	string	End of time range (ISO 8601)
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)

Example Request

curl -X GET "https://app.veraid.io/api/v1/audit-logs?actorType=IDENTITY&action=credential.used&outcome=SUCCESS&startDate=2026-03-18T00:00:00Z&endDate=2026-03-19T23:59:59Z&limit=50" \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "data": [
    {
      "id": "log_abc123",
      "actorType": "IDENTITY",
      "actorId": "id_xyz789",
      "actorName": "aws-deploy-prod",
      "action": "credential.used",
      "resourceType": "credential",
      "resourceId": "cred_def456",
      "outcome": "SUCCESS",
      "ipAddress": "10.0.1.50",
      "userAgent": "veraid-sdk/1.2.0",
      "metadata": {
        "scopes": ["secrets.read"],
        "endpoint": "/api/v1/secrets/db-url",
        "credentialName": "Production API Key"
      },
      "timestamp": "2026-03-19T09:15:00Z"
    },
    {
      "id": "log_def456",
      "actorType": "IDENTITY",
      "actorId": "id_ci_001",
      "actorName": "github-deploy-myapp",
      "action": "credential.used",
      "resourceType": "credential",
      "resourceId": "cred_ghi789",
      "outcome": "SUCCESS",
      "ipAddress": "140.82.112.0",
      "userAgent": "veraid-secrets-action/1.0.0",
      "metadata": {
        "scopes": ["secrets.read", "deploy.execute"],
        "endpoint": "/api/v1/secrets/deploy-token",
        "credentialName": "GitHub Actions Key",
        "pipelineId": "run-12345",
        "commitSha": "a1b2c3d"
      },
      "timestamp": "2026-03-19T08:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1847,
    "totalPages": 37,
    "hasMore": true
  }
}

Filtering by Denied Access

To find all denied access attempts:

curl -X GET "https://app.veraid.io/api/v1/audit-logs?outcome=DENIED&startDate=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer kd_live_abc123..."

{
  "data": [
    {
      "id": "log_denied001",
      "actorType": "IDENTITY",
      "actorId": "id_unknown",
      "actorName": "legacy-service-v1",
      "action": "secret.read",
      "resourceType": "secret",
      "resourceId": "secret_prod_db",
      "outcome": "DENIED",
      "ipAddress": "203.0.113.42",
      "userAgent": "curl/8.1.2",
      "metadata": {
        "reason": "Policy denied: IP address not in allowed range",
        "matchedPolicy": "pol_abc123",
        "policyName": "Production Secrets - Office IPs Only"
      },
      "timestamp": "2026-03-15T22:45:00Z"
    }
  ]
}

Filtering by System Actions

System-initiated actions include automated credential rotations, scheduled syncs, and anomaly detection triggers:

curl -X GET "https://app.veraid.io/api/v1/audit-logs?actorType=SYSTEM&limit=10" \
  -H "Authorization: Bearer kd_live_abc123..."

{
  "data": [
    {
      "id": "log_sys001",
      "actorType": "SYSTEM",
      "actorId": "system",
      "actorName": "VeraID System",
      "action": "credential.rotated",
      "resourceType": "credential",
      "resourceId": "cred_rotate001",
      "outcome": "SUCCESS",
      "ipAddress": "internal",
      "userAgent": "veraid-scheduler/1.0",
      "metadata": {
        "identityName": "gcp-analytics-prod",
        "rotationPolicy": "90-day auto-rotation",
        "gracePeriodHours": 24,
        "previousKeyAge": "91 days"
      },
      "timestamp": "2026-03-19T02:00:00Z"
    }
  ]
}

---

Export Audit Logs

Export audit logs in bulk for compliance reporting, archival, or analysis in external tools.

GET /api/v1/audit-logs/export

Query Parameters

Parameter	Type	Required	Description
format	string	Yes	Export format: csv or json
startDate	string	Yes	Start of time range (ISO 8601)
endDate	string	Yes	End of time range (ISO 8601)

Example Request

curl -X GET "https://app.veraid.io/api/v1/audit-logs/export?format=json&startDate=2026-03-01T00:00:00Z&endDate=2026-03-19T23:59:59Z" \
  -H "Authorization: Bearer kd_live_abc123..." \
  -o audit-logs-march.json

CSV Export

curl -X GET "https://app.veraid.io/api/v1/audit-logs/export?format=csv&startDate=2026-03-01T00:00:00Z&endDate=2026-03-19T23:59:59Z" \
  -H "Authorization: Bearer kd_live_abc123..." \
  -o audit-logs-march.csv

The CSV export includes the following columns:

id,timestamp,actorType,actorId,actorName,action,resourceType,resourceId,outcome,ipAddress,userAgent

The metadata field is serialized as a JSON string in the CSV output.

Note

Export requests for large time ranges may take several seconds. The API streams the response, so your HTTP client should support chunked transfer encoding. For very large exports (more than 1 million records), consider using narrower time ranges or filtering by specific actions or actor types.

---

Common Actions

Reference of common action values used in audit log entries:

Identity Actions

Action	Description
identity.created	A new identity was created
identity.updated	An identity’s configuration was modified
identity.suspended	An identity was suspended
identity.activated	A suspended identity was reactivated
identity.deleted	An identity was permanently deleted

Credential Actions

Action	Description
credential.created	A new credential was issued
credential.used	A credential was used to authenticate
credential.rotated	A credential was rotated (new secret generated)
credential.expired	A credential reached its expiration date
credential.revoked	A credential was manually revoked

Policy Actions

Action	Description
policy.created	A new policy was created
policy.updated	A policy was modified
policy.deleted	A policy was deleted
policy.evaluated	A policy was evaluated for an access decision
policy.violated	An access attempt violated a policy

System Actions

Action	Description
sync.started	A directory or cloud provider sync started
sync.completed	A sync operation completed
sync.failed	A sync operation failed
alert.triggered	A new alert was generated
alert.resolved	An alert was resolved

Tip

Use audit log queries with outcome=DENIED to identify identities that may need updated permissions, and outcome=FAILURE to detect integration or configuration issues that need attention.

Retention

Audit logs are retained for the duration specified by your organization’s plan:

Plan	Retention Period
Starter	90 days
Professional	1 year
Enterprise	7 years (or custom)

Exported logs are not subject to retention limits. Export regularly to maintain a complete archive if your plan’s retention period is shorter than your compliance requirements.