Identity & Access Management

Preview — pending review

This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.

List and query IAM activity (audit) events

GET
/scopes/{scopeId}/iam/activities

Lists IAM activity/audit events for the active scope, powering the Activity page audit table: each event records the actor and their email, the action type (e.g. VM.START, IAM.ROLE_ASSIGN, IAM.TOKEN_CREATE), the affected resource, the source IP, the timestamp, and the result. This single endpoint also serves the iam.activity.search_filter_sort action: q matches actor, action, and resource text; the actor, action, and status query filters mirror the UI's "All actors" / "All action types" / "Any result" selects; sorting defaults to newest-first by at. Validation: scopeId must be an accessible scope; status must be one of SUCCESS|PENDING|FAILED; action must be a known action-type string; pagination/sort parameters must be within their documented ranges — violations map to VALIDATION_FAILED (422). Async & state: Synchronous read; no state change. The audit stream is append-only; events are immutable once recorded. Errors: 401 when unauthenticated; 403 when the caller lacks audit-read permission on the scope (reader role or above); 422 on malformed filter/pagination parameters; 500 on read-model failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required.

Authorization

bearerToken
headerAuthorizationBearer <token>

An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Query Parameters

region?string

Restrict the result set to a single region.

Match^[a-z][a-z0-9-]{1,39}$
q?string

Free-text search.

sort?string

Field to sort by (entity-specific; defaults to the entity's natural order).

order?string

Sort direction.

Default"asc"
Value in"asc""desc"
page?integer

1-based page number.

Range1 <= value
Default1
pageSize?integer

Items per page (max 200).

Range1 <= value <= 200
Default50
actor?string

Filter to events performed by a single actor (display name, e.g. "Oliver Bennett" or a token actor like "ci-deploy-pipeline").

action?string

Filter by action type, e.g. VM.CREATE, IAM.ROLE_ASSIGN, IAM.TOKEN_CREATE, BILLING.BUDGET_UPDATE, AUTH.LOGIN.

status?string

Filter by event result.

Value in"SUCCESS""PENDING""FAILED"

Response Body

Paginated collection of activity events in the active scope.

application/json
  1. response
data*array<>
meta*

Pagination envelope metadata. List responses are always { data, meta } — never a naked array.

curl -X GET "https://example.com/scopes/string/iam/activities"
{  "data": [    {      "id": "string",      "at": "2019-08-24T14:15:22Z",      "actor": "string",      "actorEmail": "string",      "action": "string",      "resource": "string",      "resourceName": "string",      "ip": "string",      "status": "SUCCESS",      "actorType": "user",      "credentialId": "string"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}