Audit log
45 endpoints. Paths are relative to https://api.sandscale.dev; values in braces are ones you fill in.
API reference · Authentication · Errors
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/account/audit-logs | (Brief H item 2): the entries the signed-in person caused in their organization, with no audit:read. The organization is the caller's own and the actor is always the caller; the query takes the same filters as GET /api/v1/audit-logs. An API key or a delegated or workspace token has no account of its own: 403 person_required. |
GET | /api/v1/audit-logs | List audit logs |
GET | /api/v1/audit-logs/chain-lanes | Returns the caller's organization's audit chain lane count: in effect, and the requested one the next epoch seal applies. |
PUT | /api/v1/audit-logs/chain-lanes | Requests a lane count for the caller's organization's audit chain (1 is one strict total order, up to 64): an Owner or Admin action, audited in the transaction that records it, applied by the next epoch seal (202). |
GET | /api/v1/audit-logs/cold-segments | The organization's objects of sealed segments, oldest first, with their segment's manifest digest and signing key, and the bundle to download for offline verification. |
GET | /api/v1/audit-logs/cold-segments/{seq}/bundle | A tar of the segment's manifest, its signature, its spine and the organization's object, laid out as in the bucket, each checked against the recorded manifest before it is sent. The download is audited first: one whose audit entry cannot be written does not happen. |
GET | /api/v1/audit-logs/endpoint-activity | The entries enrolled endpoint agents uploaded, by category (awareness, staging or tamper), optionally for one device, newest first, within the plan's read window. Sandscale decides which entries belong to a category. |
POST | /api/v1/audit-logs/export | Queues an export of the caller's organization's audit log: |
GET | /api/v1/audit-logs/exports | List exports |
GET | /api/v1/audit-logs/exports/{exportID} | Get one export |
GET | /api/v1/audit-logs/exports/{exportID}/download | Download of an export |
POST | /api/v1/audit-logs/merkle/checkpoint | Seals the caller's organization's audit chain since its last checkpoint into a signed Merkle checkpoint (audit:create). At most one a minute (429 checkpoint_too_soon); 409 no_new_entries when nothing was written since the last one. |
GET | /api/v1/audit-logs/merkle/checkpoints | Lists the caller's organization's checkpoints, newest first (audit:read). |
GET | /api/v1/audit-logs/merkle/checkpoints/{seq}/verify | Re-checks one of the caller's organization's checkpoints (audit:read): the signature against the published key, the link to the previous checkpoint, and the count and root recomputed from the audit log (PostgreSQL, then the audit archive). |
GET | /api/v1/audit-logs/organization | The Organization trail, the entries of every account of the caller's Organization. The database decides who may read it: the management account, or the account registered as delegated administrator of audit.neuralinverse.io, while trusted access for audit.neuralinverse.io is enabled; anyone else gets 403 with the reason code (trusted_access_disabled, not_management_or_delegated_admin, no_organization). Every read, refused ones included, is audited in the caller's account (audit.organization_trail.read). |
GET | /api/v1/audit-logs/query | The query over the organization's entries in [from, to), hot and cold tiers alike, within the plan's read window. |
GET | /api/v1/audit-logs/retention | Answers the caller's organization's audit retention policy in force (version 0 is the default of an organization that never set one) and its last versions. |
PUT | /api/v1/audit-logs/retention | Writes the next version of the caller's organization's audit retention policy: {"expected_version", "default_days", "by_regulation", "reason"}. The route is re-verified. Shortening or removing a period also needs a person and a reason of at least 10 characters, and is refused while a legal hold covers entries the shorter period would no longer keep. |
GET | /api/v1/audit-logs/sessions | List sessions |
GET | /api/v1/audit-logs/sessions/{id}/replay | Replay of a session |
GET | /api/v1/audit-logs/storage-stats | Reports where the caller's organization's audit log is stored (every organization's, with the table size, for a super admin): the hot and cold PostgreSQL rows, and, with audit tiering, the entries moved to the audit bucket (object_storage). |
GET | /api/v1/audit-logs/stream | List stream |
GET | /api/v1/audit-logs/tiering | The organization's hot window and archive retention (from its entitlements), what it has in the cold tier and what is sealed but still hot. A super admin without organization_id sees the platform: every organization's cold tier and the latest runs. |
GET | /api/v1/audit-logs/verifications | List verifications |
POST | /api/v1/audit-logs/verifications | Create a verification |
GET | /api/v1/audit-logs/verifications/{id} | Get one verification |
GET | /api/v1/audit-logs/verify | List verify |
POST | /api/v1/audit/client-events | Records the actions a signed-in person took in a first-party app in the audit ledger. The route needs api:access; the handler then admits only a person's access token issued to a registered first-party OAuth client. The organization and user are the token's: the body may repeat them but a body naming any other is refused (403 not_own_identity) before anything is recorded. |
GET | /api/v1/audit/packs | List packs |
POST | /api/v1/audit/packs | Create a pack |
GET | /api/v1/audit/packs/{id} | Get one pack |
GET | /api/v1/audit/packs/{id}/evidence | Evidence of a pack |
GET | /api/v1/audit/packs/{id}/export | Export of a pack |
POST | /api/v1/audit/signing-keys/rotate | Create a rotate |
GET | /api/v1/audit/streams | List streams |
POST | /api/v1/audit/streams | Create a stream |
GET | /api/v1/audit/streams/{id} | Get one stream |
PATCH | /api/v1/audit/streams/{id} | Update one stream |
DELETE | /api/v1/audit/streams/{id} | Delete one stream |
PUT | /api/v1/audit/streams/{id}/pii | Set the pii of a stream |
POST | /api/v1/audit/streams/{id}/resume | Resume a stream |
GET | /api/v1/audit/streams/{id}/setup | Answers a kind's walkthrough (?kind=) or a destination's ({id}), with the Sandscale values the provider needs: for S3 the principal ARN Sandscale assumes roles as, the destination's external ID and its trust and permission policies. Nothing secret is in it. |
GET | /api/v1/audit/streams/{id}/status | Status of a stream |
POST | /api/v1/audit/streams/{id}/test | Test a stream |
GET | /api/v1/audit/streams/setup | Answers a kind's walkthrough (?kind=) or a destination's ({id}), with the Sandscale values the provider needs: for S3 the principal ARN Sandscale assumes roles as, the destination's external ID and its trust and permission policies. Nothing secret is in it. |
Endpoints
GET /api/v1/account/audit-logs
(Brief H item 2): the entries the signed-in person caused in their organization, with no audit:read. The organization is the caller's own and the actor is always the caller; the query takes the same filters as GET /api/v1/audit-logs. An API key or a delegated or workspace token has no account of its own: 403 person_required.
- Permission
signed in- Query parameters
action,action_prefix,from,include_read_only,outcome,project_activity,project_id,resource_type,to- Errors
- 400:
invalid_query; 401:unauthorized; 403:forbidden,person_required; 404:not_found; 503:unavailable
GET /api/v1/audit-logs
List audit logs
- Permission
audit:read- Query parameters
action,action_prefix,from,include_read_only,outcome,project_activity,project_id,resource_type,to- Errors
- 400:
invalid_query; 403:forbidden; 404:not_found; 503:unavailable
GET /api/v1/audit-logs/chain-lanes
Returns the caller's organization's audit chain lane count: in effect, and the requested one the next epoch seal applies.
- Permission
audit:read- Response
- 200: object of any
- Errors
- 403:
forbidden
PUT /api/v1/audit-logs/chain-lanes
Requests a lane count for the caller's organization's audit chain (1 is one strict total order, up to 64): an Owner or Admin action, audited in the transaction that records it, applied by the next epoch seal (202).
- Permission
audit.chain:configure- Request body
- object
- Response
- 202: object of any
- Errors
- 400:
invalid_body,validation_error; 403:forbidden
GET /api/v1/audit-logs/cold-segments
The organization's objects of sealed segments, oldest first, with their segment's manifest digest and signing key, and the bundle to download for offline verification.
- Permission
audit:read- Query parameters
organization_id- Response
- 200: object of any
- Errors
- 403:
forbidden; 503:tiering_unavailable
GET /api/v1/audit-logs/cold-segments/{seq}/bundle
A tar of the segment's manifest, its signature, its spine and the organization's object, laid out as in the bucket, each checked against the recorded manifest before it is sent. The download is audited first: one whose audit entry cannot be written does not happen.
- Permission
audit:read- Path parameters
seq- Query parameters
organization_id- Errors
- 403:
forbidden; 404:not_found; 409:cold_tier_integrity; 502:bucket_unavailable; 503:tiering_unavailable
GET /api/v1/audit-logs/endpoint-activity
The entries enrolled endpoint agents uploaded, by category (awareness, staging or tamper), optionally for one device, newest first, within the plan's read window. Sandscale decides which entries belong to a category.
- Permission
audit:read- Query parameters
category,device_id- Response
- 200: object of any
- Errors
- 400:
invalid_query; 403:forbidden
POST /api/v1/audit-logs/export
Queues an export of the caller's organization's audit log:
- Permission
audit:create- Request body
- object
- Response
- 202: object of any
- Errors
- 400:
invalid_body,validation_error; 403:forbidden; 404:not_found; 503:export_unavailable,unavailable
GET /api/v1/audit-logs/exports
List exports
- Permission
audit:read- Response
- 200: object of any
- Errors
- 403:
forbidden; 503:export_unavailable
GET /api/v1/audit-logs/exports/{exportID}
Get one export
- Permission
audit:read- Path parameters
exportID- Response
- 200: object of any
- Errors
- 403:
forbidden; 404:not_found; 503:export_unavailable
GET /api/v1/audit-logs/exports/{exportID}/download
Download of an export
- Permission
audit:read- Path parameters
exportID- Errors
- 403:
forbidden; 404:not_found; 409:export_integrity,export_not_ready; 410:export_expired; 503:export_unavailable
POST /api/v1/audit-logs/merkle/checkpoint
Seals the caller's organization's audit chain since its last checkpoint into a signed Merkle checkpoint (audit:create). At most one a minute (429 checkpoint_too_soon); 409 no_new_entries when nothing was written since the last one.
- Permission
audit:create- Response
- 201: object of any
- Errors
- 400:
organization_required; 403:forbidden; 409:no_new_entries; 429:checkpoint_too_soon; 503:checkpoints_unavailable
GET /api/v1/audit-logs/merkle/checkpoints
Lists the caller's organization's checkpoints, newest first (audit:read).
- Permission
audit:read- Response
- 200: object of any
- Errors
- 400:
organization_required; 503:checkpoints_unavailable
GET /api/v1/audit-logs/merkle/checkpoints/{seq}/verify
Re-checks one of the caller's organization's checkpoints (audit:read): the signature against the published key, the link to the previous checkpoint, and the count and root recomputed from the audit log (PostgreSQL, then the audit archive).
- Permission
audit:read- Path parameters
seq- Response
- 200: Verification
- Errors
- 400:
organization_required; 404:not_found; 503:checkpoints_unavailable
GET /api/v1/audit-logs/organization
The Organization trail, the entries of every account of the caller's Organization. The database decides who may read it: the management account, or the account registered as delegated administrator of audit.neuralinverse.io, while trusted access for audit.neuralinverse.io is enabled; anyone else gets 403 with the reason code (trusted_access_disabled, not_management_or_delegated_admin, no_organization). Every read, refused ones included, is audited in the caller's account (audit.organization_trail.read).
- Permission
audit:read- Query parameters
account,action,action_prefix,include_read_only,outcome,resource_type- Response
- 200: object of any
- Errors
- 400:
invalid_query; 403:forbidden
GET /api/v1/audit-logs/query
The query over the organization's entries in [from, to), hot and cold tiers alike, within the plan's read window.
- Permission
audit:read- Query parameters
from,organization_id,project_activity,query,to- Response
- 200: object of any
- Errors
- 400:
invalid_query,validation_error; 403:forbidden; 409:cold_tier_integrity; 422:query_too_wide; 429:query_busy; 503:tiering_unavailable
GET /api/v1/audit-logs/retention
Answers the caller's organization's audit retention policy in force (version 0 is the default of an organization that never set one) and its last versions.
- Permission
audit:read- Response
- 200: object of any
- Errors
- 400:
organization_required; 503:retention_unavailable
PUT /api/v1/audit-logs/retention
Writes the next version of the caller's organization's audit retention policy: {"expected_version", "default_days", "by_regulation", "reason"}. The route is re-verified. Shortening or removing a period also needs a person and a reason of at least 10 characters, and is refused while a legal hold covers entries the shorter period would no longer keep.
- Permission
audit:update- Request body
- object
- Response
- 200: object of any
- Errors
- 400:
invalid_body,organization_required,reason_required,validation_error; 403:elevation_required,person_required; 409:legal_hold_active,version_conflict; 503:retention_unavailable
GET /api/v1/audit-logs/sessions
List sessions
- Permission
audit:read- Response
- 200: object of any
- Errors
- 403:
forbidden
GET /api/v1/audit-logs/sessions/{id}/replay
Replay of a session
- Permission
audit:read- Path parameters
id- Response
- 200: object of any
- Errors
- 403:
forbidden
GET /api/v1/audit-logs/storage-stats
Reports where the caller's organization's audit log is stored (every organization's, with the table size, for a super admin): the hot and cold PostgreSQL rows, and, with audit tiering, the entries moved to the audit bucket (object_storage).
- Permission
audit:read- Response
- 200: object of any
- Errors
- 403:
forbidden
GET /api/v1/audit-logs/stream
List stream
- Permission
audit:read- Errors
- 400:
invalid_query; 401:unauthorized
GET /api/v1/audit-logs/tiering
The organization's hot window and archive retention (from its entitlements), what it has in the cold tier and what is sealed but still hot. A super admin without organization_id sees the platform: every organization's cold tier and the latest runs.
- Permission
audit:read- Query parameters
organization_id- Response
- 200: object of any
- Errors
- 403:
forbidden; 503:tiering_unavailable
GET /api/v1/audit-logs/verifications
List verifications
- Permission
audit:read- Query parameters
limit- Response
- 200: object of any
- Errors
- 403:
forbidden; 503:unavailable
POST /api/v1/audit-logs/verifications
Create a verification
GET /api/v1/audit-logs/verifications/{id}
Get one verification
- Permission
audit:read- Path parameters
id- Response
- 200: Job
- Errors
- 403:
forbidden; 404:not_found; 503:unavailable
GET /api/v1/audit-logs/verify
List verify
- Permission
audit:read- Query parameters
from,to- Response
- 200: Result
- Errors
- 400:
validation_error; 403:forbidden; 422:range_too_large; 503:unavailable
POST /api/v1/audit/client-events
Records the actions a signed-in person took in a first-party app in the audit ledger. The route needs api:access; the handler then admits only a person's access token issued to a registered first-party OAuth client. The organization and user are the token's: the body may repeat them but a body naming any other is refused (403 not_own_identity) before anything is recorded.
- Permission
api:access- Response
- 200: object
- Errors
- 400:
invalid_request; 401:unauthorized; 403:api_key_not_allowed,client_not_first_party,not_own_identity; 413:batch_too_large,payload_too_large; 415:content_type; 503:dlp_unavailable
GET /api/v1/audit/packs
List packs
- Permission
audit:read- Query parameters
framework- Response
- 200: object of any
- Errors
- 401:
unauthorized
POST /api/v1/audit/packs
Create a pack
- Permission
audit:create- Request body
- object
- Response
- 201: EvidencePack
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 415:content_type
GET /api/v1/audit/packs/{id}
Get one pack
- Permission
audit:read- Path parameters
id- Response
- 200: EvidencePack
- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found
GET /api/v1/audit/packs/{id}/evidence
Evidence of a pack
- Permission
audit:read- Path parameters
id- Response
- 200: object of any
- Errors
- 400:
validation_error; 401:unauthorized
GET /api/v1/audit/packs/{id}/export
Export of a pack
- Permission
audit:read- Path parameters
id- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found
POST /api/v1/audit/signing-keys/rotate
Create a rotate
- Permission
audit:update- Response
- 200: object of any
- Errors
- 403:
forbidden
GET /api/v1/audit/streams
List streams
- Permission
audit:read- Response
- 200: object of any
- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
POST /api/v1/audit/streams
Create a stream
- Permission
audit:admin- Request body
- auditStreamBody
- Response
- 201: Destination
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 415:content_type; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
GET /api/v1/audit/streams/{id}
Get one stream
- Permission
audit:read- Path parameters
id- Response
- 200: Destination
- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
PATCH /api/v1/audit/streams/{id}
Update one stream
- Permission
audit:admin- Path parameters
id- Request body
- auditStreamBody
- Response
- 200: Destination
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 415:content_type; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
DELETE /api/v1/audit/streams/{id}
Delete one stream
- Permission
audit:admin- Path parameters
id- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
PUT /api/v1/audit/streams/{id}/pii
Set the pii of a stream
- Permission
audit:admin- Path parameters
id- Request body
- object
- Response
- 200: Destination
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 415:content_type; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
POST /api/v1/audit/streams/{id}/resume
Resume a stream
- Permission
audit:admin- Path parameters
id- Response
- 200: Destination
- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
GET /api/v1/audit/streams/{id}/setup
Answers a kind's walkthrough (?kind=) or a destination's ({id}), with the Sandscale values the provider needs: for S3 the principal ARN Sandscale assumes roles as, the destination's external ID and its trust and permission policies. Nothing secret is in it.
- Permission
audit:read- Path parameters
id- Query parameters
kind- Response
- 200: Setup
- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
GET /api/v1/audit/streams/{id}/status
Status of a stream
- Permission
audit:read- Path parameters
id- Response
- 200: Status
- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
POST /api/v1/audit/streams/{id}/test
Test a stream
- Permission
audit:admin- Path parameters
id- Response
- 200: TestResult
- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
GET /api/v1/audit/streams/setup
Answers a kind's walkthrough (?kind=) or a destination's ({id}), with the Sandscale values the provider needs: for S3 the principal ARN Sandscale assumes roles as, the destination's external ID and its trust and permission policies. Nothing secret is in it.
- Permission
audit:read- Query parameters
kind- Response
- 200: Setup
- Errors
- 400:
validation_error; 401:unauthorized; 404:not_found; 409:conflict,destination_unreadable,limit_reached; 422:egress_refused; 429:rate_limited; 503:audit_unavailable,credential_store_unavailable
Objects
object
| Field | Type | Description |
|---|---|---|
format | string | |
from | string | |
to | string | |
action | string | |
action_prefix optional | string | |
resource_type | string | |
outcome | string | |
project_id | string |
object
| Field | Type | Description |
|---|---|---|
from | string | |
to | string |
object
| Field | Type | Description |
|---|---|---|
framework | string | |
period_start | string | |
period_end | string |
object
| Field | Type | Description |
|---|---|---|
lanes optional | integer |
object
| Field | Type | Description |
|---|---|---|
expected_version optional | integer | |
default_days optional | integer | |
by_regulation | object of integer | |
reason | string |
object
| Field | Type | Description |
|---|---|---|
include_pii optional | boolean |
object
| Field | Type | Description |
|---|---|---|
results | array of Result | |
accepted | integer | |
duplicates | integer | |
rejected | integer | |
client | v1.clientSource |
EvidencePack
A container for a set of evidence items covering a compliance framework within a reporting period.
| Field | Type | Description |
|---|---|---|
ID | string | |
OrgID | string | |
Framework | string | |
PeriodStart | timestamp | |
PeriodEnd | timestamp | |
Status | string | |
EvidenceCount | integer | |
GeneratedAt | timestamp | |
Summary | object of any |
Credential
Credential describes a destination's stored credential, never its value.
| Field | Type | Description |
|---|---|---|
configured | boolean | |
fields | array of string | |
version | integer | |
updated_at optional | timestamp |
Destination
An organization's audit stream destination as the API returns it.
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | |
kind | string | |
format | string | |
enabled | boolean | |
state | string | |
state_reason | string | |
state_changed_at | timestamp | |
include_pii | boolean | |
settings | object of string | |
credential | Credential | |
filters | Filters | |
filters_changed_at | timestamp | When the filters last changed (zero: never since creation). |
created_at | timestamp | |
created_by optional | string | |
updated_at | timestamp | |
updated_by optional | string | |
row_error optional | string | RowError says why the stored row cannot be used (settings or filters that do not decode). Such a destination is never delivered to; delete it and create it again. |
Filters
Filters choose the entries a destination receives. Entries a filter leaves out still move the cursor: the destination asked not to receive them.
| Field | Type | Description |
|---|---|---|
action_prefixes optional | array of string | |
exclude_action_prefixes optional | array of string | |
min_severity optional | integer |
LaneStatus
A destination's position in one lane.
| Field | Type | Description |
|---|---|---|
lane_key | string | |
delivered_seq | integer | |
head_seq | integer | |
lag_entries | integer | |
lag_seconds | integer | |
stopped_reason optional | string | |
stopped_at optional | timestamp |
Setup
| Field | Type | Description |
|---|---|---|
kind | string | |
destination_id optional | string | Set for a destination's walkthrough. |
principal_arn optional | string | The AWS identity Sandscale assumes roles as, when the operator configured it. |
guide | Guide |
Status
A destination's delivery status.
| Field | Type | Description |
|---|---|---|
destination_id | string | |
state | string | |
state_reason | string | |
enabled | boolean | |
delivered_total | integer | |
failed_total | integer | |
consecutive_failures | integer | |
last_attempt_at optional | timestamp | |
last_success_at optional | timestamp | |
last_error_at optional | timestamp | |
last_error_class optional | string | |
next_attempt_at optional | timestamp | |
lag_entries | integer | |
lag_seconds | integer | |
lanes | array of LaneStatus |
TestResult
The outcome of a connection test.
| Field | Type | Description |
|---|---|---|
ok | boolean | |
error_class optional | string | |
message optional | string | |
tested_at | timestamp | |
code optional | string | The stable code of the failure: the error class, or the stage code assume_role_denied or sign_in_refused. The kind's walkthrough has its fix. |
result | Result | The test as staged checks. |
Break
The first entry whose signature or link does not hold.
| Field | Type | Description |
|---|---|---|
id | integer | |
at | timestamp | |
reason | string |
CheckpointView
The last signed checkpoint at or before the range's end.
| Field | Type | Description |
|---|---|---|
checkpoint_id | string | |
end_event_id | string | |
end_timestamp | timestamp | |
key_id | string | |
signature_valid | boolean |
Explanation
A verification's result in plain words. Sandscale writes it; the console shows it as it is.
| Field | Type | Description |
|---|---|---|
status | string | ExplanationIntact, ExplanationBroken or ExplanationCheckpointInvalid. |
label | string | The result in two or three words. |
summary | string | What was checked and what was found. |
break_reason optional | string | BreakReason says why the first break is a break and what it can mean; empty without one. |
details | array of string | Further facts of the run, one sentence each. |
FormUse
FormUse counts the entries of a verification that verified in one earlier signed form.
| Field | Type | Description |
|---|---|---|
form | string | |
description | string | |
entries | integer | |
first_id | integer | |
last_id | integer |
Job
A verification run as a job.
| Field | Type | Description |
|---|---|---|
id | string | |
org_id | string | |
requested_by optional | string | |
status | string | |
error optional | string | |
result | Result | |
created_at | timestamp | |
started_at optional | timestamp | |
completed_at optional | timestamp | |
expires_at | timestamp | |
currency optional | string | Currency says whether a completed result is the one to read: CurrencyCurrent, or CurrencySuperseded when a newer passing run of the same chain covers its range. Derived when the job is read, never stored; empty until the job completes. |
superseded_by optional | Superseder | SupersededBy names the newer passing run, set with CurrencySuperseded. The older row stays exactly as it was written (append-only): it is the record of what that run found. |
RangeView
The range with the first and last entry checked.
| Field | Type | Description |
|---|---|---|
from | timestamp | |
to | timestamp | |
first_id optional | integer | |
last_id optional | integer |
Result
| Field | Type | Description |
|---|---|---|
verified | integer | |
first_break optional | Break | |
range | RangeView | |
checkpoint optional | CheckpointView | |
cold_links | integer | |
write_time_forms | array of FormUse | The entries that verified in an earlier signed form: an earlier server version signed their metadata in another key order than the ledger stores it in. They verify; the result says so. |
explanation optional | Explanation | The result in plain words, derived from the fields above whenever a result is returned (never stored); nil while a job has not completed. |
Superseder
The newer passing run that supersedes an older failing one.
| Field | Type | Description |
|---|---|---|
id | string | |
completed_at | timestamp | |
verified | integer | The number of entries the newer run verified. |
note | string | Note says in plain words why the older result is superseded and what is kept. |
Problem
Problem says why an event was rejected.
| Field | Type | Description |
|---|---|---|
code | string | |
message | string |
Result
The outcome of one event of a batch, in request order.
| Field | Type | Description |
|---|---|---|
index | integer | |
client_event_id optional | string | |
status | string | "accepted" (recorded now), "duplicate" (recorded by an earlier request or an earlier event of this one) or "rejected". |
id optional | string | The audit entry's id, the same for an event and every retry of it. |
duplicate | boolean | |
recorded_at optional | timestamp | |
error optional | Problem |
Verification
The verifier's answer.
| Field | Type | Description |
|---|---|---|
seq | integer | |
valid | boolean | |
signature_valid | boolean | |
post_quantum | boolean | |
key_id | string | |
key_status | string | |
merkle_root_matches | boolean | |
recomputed_event_count | integer | |
event_count_matches | boolean | |
entries_valid | boolean | EntriesValid: every sealed entry's hash is the signature of its stored content, each entry links to its predecessor in the lane by previous_hash, and each lane's first and last entry are the ids the checkpoint names. |
previous_linked | boolean | PreviousLinked: the checkpoint names the hash of the previous checkpoint's payload (or is the first). |
contiguous | boolean | Contiguous: every lane goes on where the previous checkpoint ended it (from_seq is the previous to_seq + 1) and no lane the previous checkpoint named is missing. Always true for the first checkpoint. |
from_archive | integer | How many leaves were read from the audit archive. |
reasons | array of string |
Check
One staged check of a test.
| Field | Type | Description |
|---|---|---|
Key | string | Stable ("connect", "bind", "search_base"). |
Label | string | |
State | string | StatePassed, StateFailed, StateWaiting or StateSkipped (an earlier check failed, or the check does not apply). |
Code optional | string | Code names the Problem of a failed or waiting check. |
Detail optional | string | Sandscale's own wording of what it found, never a provider's raw error text. |
Field
One provider value to paste back into a Sandscale form field.
| Field | Type | Description |
|---|---|---|
Name | string | The Sandscale field it fills (the API's JSON name). |
Label | string | The Sandscale form's label. |
ProviderLabel | string | What the provider calls it ("Application (client) ID"). |
Guide
One integration variant's walkthrough.
| Field | Type | Description |
|---|---|---|
Integration | string | Integration names the integration ("scim", "social", "ldap", "dns", "sso"). |
Variant optional | string | The provider or preset ("entra_id", "okta", "active_directory"). |
Title | string | |
ProviderUi optional | string | ProviderUI names the console the click paths are in ("Microsoft Entra admin center"). |
ReviewedAt | string | The date (YYYY-MM-DD) the click paths were last checked against the provider's console and documentation. |
Steps | array of Step | |
Values | object of string | The Sandscale values the steps name, by source: only real values of the caller's configuration, absolute URLs. A source with no value yet is absent. |
Notes optional | array of Note | |
Verify optional | Verify | |
Problems optional | array of Problem | |
DocsPath optional | string | The generated public page, relative to the repository. |
Note
A notice next to the steps.
| Field | Type | Description |
|---|---|---|
Title | string | |
Text | string | |
Tone optional | string | "info" (empty) or "warning". |
Problem
One troubleshooting entry; a test result or the provider names it by Code.
| Field | Type | Description |
|---|---|---|
Code | string | |
Title | string | |
Cause | string | |
Fix | string | |
Settings optional | array of string | The provider settings to change, in order. |
Result
The one answer of every integration's test, so one console component renders them all: the overall state, the code of the first failing check (a Problem of the guide names the fix), Sandscale's own message and the staged checks in the order they ran.
| Field | Type | Description |
|---|---|---|
State | string | StatePassed, StateFailed or StateWaiting (nothing to fail yet, such as a SCIM token no identity provider has used). |
Code optional | string | |
Message | string | |
Checks | array of Check | |
TestedAt | timestamp | When Sandscale ran the checks. |
Step
One step of a walkthrough.
| Field | Type | Description |
|---|---|---|
Key | string | Stable within the guide ("register_app", "provisioning"). |
Where optional | string | |
WizardStep optional | string | Wizard names the Identity Center wizard step the step belongs to. |
Title | string | |
ClickPath optional | array of string | The path through the provider's console, one item per click. |
Values optional | array of Value | What to enter at the provider. |
PasteBack optional | array of Field | The provider's values to bring back into Sandscale. |
Text | string | Text says what to do there. |
Value
One value to enter at the provider: Source names a Sandscale value of Guide.Values (the console shows it with a copy button), Literal is a fixed value.
| Field | Type | Description |
|---|---|---|
Label | string | |
Source optional | string | |
Literal optional | string | |
Format optional | string | FormatText (empty), FormatCommand or FormatJSON. |
Secret optional | boolean | Secret: the value is shown once, when Sandscale issues it (a token); it is never in Guide.Values afterwards. |
Verify
Verify says how the administrator proves the connection works.
| Field | Type | Description |
|---|---|---|
Action | string | What the console offers: "TEST_CONNECTION", "WAIT_FOR_FIRST_REQUEST", "SIGN_IN", "CHECK_DNS". |
Label | string | |
Text | string | Text says what success looks like. |
auditStreamBody
A create or update body. OrgID and OrganizationID are accepted and ignored: the organization is the caller's. IncludePII is refused here: it has its own route.
| Field | Type | Description |
|---|---|---|
name optional | string | |
kind optional | string | |
format optional | string | |
enabled optional | boolean | |
settings | object of string | |
credentials | object of string | |
filters optional | Filters | |
include_pii optional | boolean | |
org_id optional | string | |
organization_id optional | string |
clientSource
What the request's client was recorded as: the verified OAuth client id of the token, and the declared name and version ("" when absent or malformed).
| Field | Type | Description |
|---|---|---|
id | string | |
name optional | string | |
version optional | string |
This page is generated from the server's route table and the Go handlers that serve each route. Do not edit it by hand.