Skip to content

Commit 1fb3787

Browse files
pmdroidgithub-actions[bot]
pmdroid
and
github-actions[bot]
authored
feat: added docs for audit logs (#817)
* feat: added docs for audit logs * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Regenerate clean markdown files * 🤖 Regenerate LLMs.txt * Regenerate clean markdown files * Regenerate clean markdown files * Regenerate clean markdown files * fix: endpoint uri * Regenerate clean markdown files * Regenerate clean markdown files * Regenerate clean markdown files * Regenerate clean markdown files * Regenerate clean markdown files * fix: added image for new ui and small intro * Regenerate clean markdown files * Regenerate clean markdown files * Regenerate clean markdown files * Regenerate clean markdown files --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
1 parent 2eacf15 commit 1fb3787

5 files changed

Lines changed: 870 additions & 1 deletion

File tree

‎app/en/guides/_meta.tsx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
import type { MetaRecord } from "nextra";
22

33
export const meta: MetaRecord = {
4+
"audit-logs": {
5+
title: "Audit Logs",
6+
},
47
"contextual-access": {
58
title: "Contextual Access",
69
},

‎app/en/guides/audit-logs/page.mdx‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
---
2+
title: "Audit Logs"
3+
description: "Arcade.dev now captures every administrative action across the platform automatically — who did it, how, what changed, and when."
4+
---
5+
6+
# Audit Logs for AI Agent Platforms
7+
8+
TL;DR: Arcade.dev captures every administrative action across the runtime automatically — who did it, how, what changed, and when. There's nothing to enable. Audit logs are on by default, with a filterable dashboard and a REST API for pulling data into your own systems.
9+
10+
![Audit Log Dashboard](/images/screenshots/audit-log.png)
11+
12+
If you want audit events outside the dashboard, there's a REST API. You can pull logs programmatically to feed into your existing SIEM, compliance tooling, or internal reporting.
13+
14+
## Example
15+
16+
Fetch the 10 most recent audit logs for your organization, filtered to creation events:
17+
18+
```bash
19+
curl -s "https://cloud.arcade.dev/api/v1/orgs/{org_id}/audit_logs?action=AUDIT_ACTION_CREATED&limit=10" \
20+
-H "Authorization: Bearer $ARCADE_API_KEY"
21+
```
22+
23+
```json
24+
{
25+
"code": 200,
26+
"msg": "Request successful",
27+
"data": {
28+
"items": [
29+
{
30+
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
31+
"event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
32+
"timestamp": "2026-02-24T12:34:56.789Z",
33+
"action": "AUDIT_ACTION_CREATED",
34+
"source": "AUDIT_SOURCE_API",
35+
"display_name": "jane@example.com",
36+
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
37+
"principal_type": "ACCOUNT",
38+
"resource_type": "RESOURCE_TYPE_API_KEY",
39+
"resource_display": "prod-key-1"
40+
}
41+
],
42+
"next_cursor": "MjAyNi0wMi0yNFQxMjo...",
43+
"has_more": true
44+
}
45+
}
46+
```
47+
48+
To fetch the next page, pass the cursor:
49+
50+
```bash
51+
curl -s "https://cloud.arcade.dev/api/v1/orgs/{org_id}/audit_logs?action=AUDIT_ACTION_CREATED&limit=10&cursor=MjAyNi0wMi0yNFQxMjo..." \
52+
-H "Authorization: Bearer $ARCADE_API_KEY"
53+
```
54+
55+
## Endpoints overview
56+
57+
| Endpoint | Method | Description | Auth |
58+
| -- | -- | -- | -- |
59+
| `/api/v1/orgs/{org_id}/audit_logs` | GET | List audit logs for an organization | User (API key/JWT) |
60+
| `/api/v1/orgs/{org_id}/projects/{project_id}/audit_logs` | GET | List audit logs for a project | User (API key/JWT) |
61+
62+
## List Organization Audit Logs
63+
64+
```
65+
GET /api/v1/orgs/{org_id}/audit_logs
66+
```
67+
68+
Returns a paginated, cursor-based list of audit log entries scoped to an organization. Results are ordered newest-first.
69+
70+
### Authentication
71+
72+
Requires a valid user identity (API key or bearer token). The authenticated principal must be a member of the organization.
73+
74+
### Rate limit
75+
76+
100 requests per 60 seconds (per IP).
77+
78+
### Path parameters
79+
80+
| Parameter | Type | Required | Description |
81+
| -- | -- | -- | -- |
82+
| `org_id` | UUID | Yes | Organization ID |
83+
84+
### Query parameters
85+
86+
| Parameter | Type | Required | Default | Constraints | Description |
87+
| -- | -- | -- | -- | -- | -- |
88+
| `action` | string | No | `null` | \-- | Filter by action (for example `AUDIT_ACTION_CREATED`) |
89+
| `source` | string | No | `null` | \-- | Filter by source (for example `AUDIT_SOURCE_API`) |
90+
| `resource_type` | string | No | `null` | \-- | Filter by resource type |
91+
| `cursor` | string | No | `null` | \-- | Pagination cursor from a previous response |
92+
| `limit` | int | No | `50` | `1` -- `100` | Number of results per page |
93+
94+
### Response
95+
96+
**Status:** `200 OK`
97+
98+
```json
99+
{
100+
"code": 200,
101+
"msg": "Request successful",
102+
"data": {
103+
"items": [
104+
{
105+
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
106+
"event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
107+
"timestamp": "2026-02-24T12:34:56.789Z",
108+
"client_ip": "203.0.113.42",
109+
"action": "AUDIT_ACTION_CREATED",
110+
"source": "AUDIT_SOURCE_DASHBOARD",
111+
"display_name": "jane@example.com",
112+
"customer_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
113+
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
114+
"project_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
115+
"principal_id": "usr_abc123",
116+
"user_id": "user-456",
117+
"principal_type": "ACCOUNT",
118+
"resource_type": "RESOURCE_TYPE_PROJECT",
119+
"resource_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
120+
"resource_display": "My Project",
121+
"data": { "key": "value" },
122+
"created_time": "2026-02-24T12:34:57.000Z"
123+
}
124+
],
125+
"next_cursor": "MjAyNi0wMi0yNFQxMjo...",
126+
"has_more": true
127+
}
128+
}
129+
```
130+
131+
### Pagination
132+
133+
Pagination is cursor-based. When `has_more` is `true`, pass the `next_cursor` value as the `cursor` query parameter in the next request. The cursor is an opaque base64-encoded string; do not construct or modify it.
134+
135+
---
136+
137+
## List Project Audit Logs
138+
139+
```
140+
GET /api/v1/orgs/{org_id}/projects/{project_id}/audit_logs
141+
```
142+
143+
Identical to the organization endpoint, but additionally scoped to a single project. The authenticated principal must have access to both the organization and the project.
144+
145+
### Authentication
146+
147+
Requires a valid user identity (API key or bearer token). The principal must be a member of both the organization and the project.
148+
149+
### Rate limit
150+
151+
100 requests per 60 seconds (per IP).
152+
153+
### Path parameters
154+
155+
| Parameter | Type | Required | Description |
156+
| -- | -- | -- | -- |
157+
| `org_id` | UUID | Yes | Organization ID |
158+
| `project_id` | UUID | Yes | Project ID |
159+
160+
### Query parameters
161+
162+
Same as [List Organization Audit Logs](<#query-parameters>).
163+
164+
### Response
165+
166+
Same schema as [List Organization Audit Logs](<#response>). The `project_id` filter is applied automatically from the path.
167+
168+
---
169+
170+
## Enums
171+
172+
### AuditAction
173+
174+
| Value | Number | Description |
175+
| -- | -- | -- |
176+
| `AUDIT_ACTION_UNSPECIFIED` | 0 | Default / unknown |
177+
| `AUDIT_ACTION_CREATED` | 1 | Resource was created |
178+
| `AUDIT_ACTION_UPDATED` | 2 | Resource was updated |
179+
| `AUDIT_ACTION_DELETED` | 3 | Resource was deleted |
180+
| `AUDIT_ACTION_DISABLED` | 4 | Resource was disabled |
181+
182+
### AuditSource
183+
184+
| Value | Number | Description |
185+
| -- | -- | -- |
186+
| `AUDIT_SOURCE_UNSPECIFIED` | 0 | Default / unknown |
187+
| `AUDIT_SOURCE_API` | 1 | API call |
188+
| `AUDIT_SOURCE_DASHBOARD` | 2 | Dashboard action |
189+
| `AUDIT_SOURCE_CLI` | 3 | CLI invocation |
190+
| `AUDIT_SOURCE_SDK` | 4 | SDK call |
191+
| `AUDIT_SOURCE_SYSTEM` | 5 | Internal system operation |
192+
193+
### ResourceType
194+
195+
| Value | Number | Description |
196+
| -- | -- | -- |
197+
| `RESOURCE_TYPE_UNSPECIFIED` | 0 | Default / unknown |
198+
| `RESOURCE_TYPE_API_KEY` | 1 | API key |
199+
| `RESOURCE_TYPE_CUSTOMER` | 2 | Customer |
200+
| `RESOURCE_TYPE_INVITATION` | 3 | Invitation |
201+
| `RESOURCE_TYPE_ORGANIZATION` | 4 | Organization |
202+
| `RESOURCE_TYPE_PROJECT` | 5 | Project |
203+
| `RESOURCE_TYPE_PROJECT_MEMBER` | 6 | Project member |
204+
| `RESOURCE_TYPE_USER` | 7 | User |
205+
| `RESOURCE_TYPE_WORKER` | 8 | Worker |
206+
| `RESOURCE_TYPE_GATEWAY` | 9 | Gateway |
207+
| `RESOURCE_TYPE_PLUGIN` | 10 | Plugin |
208+
| `RESOURCE_TYPE_HOOK` | 11 | Hook |
209+
| `RESOURCE_TYPE_MODEL` | 12 | Model |
210+
| `RESOURCE_TYPE_AUTH_PROVIDER` | 13 | Auth provider |
211+
| `RESOURCE_TYPE_SECRET` | 14 | Secret |
212+
| `RESOURCE_TYPE_USER_CONNECTION` | 15 | User connection |
213+
| `RESOURCE_TYPE_DEPLOYMENT` | 16 | Deployment |
214+
| `RESOURCE_TYPE_SETTING` | 17 | Setting |
215+
216+
---
217+
218+
## Response item schema
219+
220+
Each item in the `items` array of a list response has the following shape:
221+
222+
| Field | Type | Description |
223+
| -- | -- | -- |
224+
| `id` | UUID | Internal database ID |
225+
| `event_id` | UUID | Event identifier |
226+
| `timestamp` | datetime (ISO) | When the event occurred |
227+
| `client_ip` | string / null | Originating client IP |
228+
| `action` | string | Action name (see AuditAction) |
229+
| `source` | string | Source name (see AuditSource) |
230+
| `display_name` | string | Human-readable caller identity |
231+
| `customer_id` | UUID / null | Customer ID |
232+
| `organization_id` | UUID | Organization ID |
233+
| `project_id` | UUID / null | Project ID |
234+
| `principal_id` | string | Principal ID |
235+
| `user_id` | string / null | User ID |
236+
| `principal_type` | string | Principal type (for example `ACCOUNT`) |
237+
| `resource_type` | string / null | Resource type (see ResourceType) |
238+
| `resource_id` | string / null | Resource identifier |
239+
| `resource_display` | string / null | Human-readable resource name |
240+
| `data` | object / null | Structured event payload |
241+
| `created_time` | datetime (ISO) | When the record was persisted |
242+
243+
---
244+
245+
## Failure handling
246+
247+
* Standard error envelope with `code` and `msg` fields. Common failures are `401` (unauthenticated), `403` (not a member of the org/project), and `429` (rate limited).

0 commit comments

Comments
 (0)