Core Concepts
The building blocks of LogStitch. Understanding these concepts will help you design your audit log integration.
Organizations#
An organization is your company's LogStitch account. It is the top-level container for everything you create — projects, API keys, team members, and billing. When you sign up for LogStitch, an organization is created for you automatically.
Projects#
A project represents a product or application within your organization. Events, API keys, and redaction rules are all scoped to a single project. If your company ships multiple products, create a project for each one to keep their audit logs separate.
Tenants#
Tenants are your customers. Every event you send to LogStitch includes a tenant_id that identifies which of your customers the event belongs to. The embeddable log viewer uses this field to show each customer only their own activity.
Events#
Events are immutable, structured records of something that happened in your application. Once ingested, events cannot be modified or deleted.
Key event fields
| Name | Type | Required | Description |
|---|---|---|---|
| action | string | Required | Dot-namespaced, past tense identifier (e.g. user.created, document.shared). |
| category | string | Required | One of: auth, access, mutation, admin, security, system. |
| actor | object | Required | The user or service that performed the action. Includes id, type, and optional name/email. |
| tenant_id | string | Required | Identifies which of your customers this event belongs to. |
| target | object | Optional | The resource being acted upon. Includes id, type, and optional name. |
| metadata | object | Optional | Arbitrary key-value pairs for additional context. Subject to PII redaction rules. |
API Keys#
LogStitch uses two types of API keys. Master keys (prefixed mk_) have full administrative access to your organization. Project keys (prefixed pk_) are scoped to a single project and used for event ingestion, querying, and creating viewer tokens.
Key security
Never expose master keys or project keys in client-side code. Use them server-side only. Viewer tokens are the only credential safe for the browser.
ID Formats#
LogStitch IDs use type prefixes for easy identification. Most use ULID format, while viewer tokens use JWTs.
ID prefixes
| Name | Type | Required | Description |
|---|---|---|---|
| evt_ | ULID | Required | Event IDs. |
| mk_ | ULID | Required | Master key IDs. |
| pk_ | ULID | Required | Project key IDs. |
| vt_ | JWT | Required | Viewer token IDs. |
Action Naming#
Actions are dot-namespaced, lowercase, and use past tense. The format describes what resource was affected and what happened to it.
// resource.action_performed
'user.created'
'document.shared'
'member.invited'
'api_key.rotated'
'permission.revoked'Actions must match the pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$
Categories#
Every event must have one of six categories. Categories help organize and filter events in the log viewer and API queries.
Event categories
| Name | Type | Required | Description |
|---|---|---|---|
| auth | category | Optional | Authentication events — sign in, sign out, password changes, MFA. |
| access | category | Optional | Resource access events — viewing, downloading, or reading data. |
| mutation | category | Optional | Data changes — creating, updating, or deleting resources. |
| admin | category | Optional | Administrative actions — managing users, roles, settings, billing. |
| security | category | Optional | Security-related events — permission changes, key rotations, suspicious activity. |
| system | category | Optional | System events — automated actions, cron jobs, integrations, webhooks. |