Approvals, policies and the kill switch
39 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/approval-channels | List approval channels |
POST | /api/v1/approval-channels | Create an approval channel |
DELETE | /api/v1/approval-channels/{id} | Delete one approval channel |
POST | /api/v1/approvals | Create an approval |
GET | /api/v1/approvals/{id} | One request, to a caller the inbox would show it to; any other request is not found. |
POST | /api/v1/approvals/{id}/dispatch | Dispatch an approval |
POST | /api/v1/approvals/{id}/issue-token | (also POST /api/v1/approvals/{id}/token) |
POST | /api/v1/approvals/{id}/token | (also POST /api/v1/approvals/{id}/token) |
POST | /api/v1/approvals/{id}/vote | Vote an approval |
GET | /api/v1/approvals/inbox | List inbox |
GET | /api/v1/approvals/inbox/{id} | Get one inbox |
POST | /api/v1/approvals/inbox/{id}/decision | Decision an inbox |
GET | /api/v1/approvals/metrics | List metrics |
GET | /api/v1/approvals/pending | The open requests the caller may see, filtered as the inbox filters them, never every request of the organization to any member. |
GET | /api/v1/approvals/poll | List poll |
GET | /api/v1/approvals/recurring | Org_id defaults to the caller's organization. |
POST | /api/v1/approvals/recurring | Create a recurring |
POST | /api/v1/approvals/redeem | Create a redeem |
GET | /api/v1/approvals/settings | List settings |
GET | /api/v1/approvals/sla | List sla |
PUT | /api/v1/approvals/sla | Set sla |
POST | /api/v1/approvals/sla/process | (admin) |
POST | /api/v1/approvals/verify-token | Create a verify token |
GET | /api/v1/dlp/builtin-patterns | List builtin patterns |
GET | /api/v1/dlp/context-rules | List context rules |
POST | /api/v1/dlp/context-rules | Create a context rule |
DELETE | /api/v1/dlp/context-rules/{id} | Delete one context rule |
POST | /api/v1/dlp/detokenize | Create a detokenize |
GET | /api/v1/dlp/enforcement | List enforcement |
GET | /api/v1/dlp/patterns | List patterns |
POST | /api/v1/dlp/patterns | Create a pattern |
DELETE | /api/v1/dlp/patterns/{id} | Delete one pattern |
POST | /api/v1/dlp/scan | Create a scan |
GET | /api/v1/dlp/stats | List stats |
POST | /api/v1/dlp/tokenize | Create a tokenize |
GET | /api/v1/dlp/violations | The caller's organization's violations, newest first. type keeps one pattern type and tool the violations whose tool_name equals it exactly (1 to 128 printable characters); both are applied before the limit. |
POST | /api/v1/dlp/violations/{id}/false-positive | False positive a violation |
GET | /api/v1/orgs/{orgID}/governance/killswitch | List killswitch |
PUT | /api/v1/orgs/{orgID}/governance/killswitch | Turns the organization's workspace kill switch on or off (governance:manage). The change and its audit entry commit together. |
Endpoints
GET /api/v1/approval-channels
List approval channels
- Permission
api:access- Query parameters
org_id
POST /api/v1/approval-channels
Create an approval channel
- Permission
approvals:admin- Request body
- object
DELETE /api/v1/approval-channels/{id}
Delete one approval channel
- Permission
approvals:admin- Path parameters
id
POST /api/v1/approvals
Create an approval
- Permission
api:access- Request body
- ApprovalRequest
- Response
- 201: ApprovalRequest
- Errors
- 400:
project_mismatch; 403:not_project_member; 404:project_not_found; 409:project_inactive; 503:projects_unavailable
GET /api/v1/approvals/{id}
One request, to a caller the inbox would show it to; any other request is not found.
- Permission
api:access- Path parameters
id- Response
- 200: ApprovalRequest
- Errors
- 400:
no_organization; 401:unauthorized
POST /api/v1/approvals/{id}/dispatch
Dispatch an approval
- Permission
api:access- Path parameters
id- Response
- 200: object of string
POST /api/v1/approvals/{id}/issue-token
(also POST /api/v1/approvals/{id}/token)
- Permission
api:access- Path parameters
id- Request body
- object
- Response
- 201: object of string
- Errors
- 403:
person_required
POST /api/v1/approvals/{id}/token
(also POST /api/v1/approvals/{id}/token)
- Permission
api:access- Path parameters
id- Request body
- object
- Response
- 201: object of string
- Errors
- 403:
person_required
POST /api/v1/approvals/{id}/vote
Vote an approval
- Permission
api:access- Path parameters
id- Request body
- object
- Response
- 200: object of string
- Errors
- 403:
person_required
GET /api/v1/approvals/inbox
List inbox
- Permission
api:access- Query parameters
cursor,limit,relation,source,view- Response
- 200: InboxPage
- Errors
- 400:
no_organization,reason_required,scope_required,validation_error; 401:unauthorized; 403:not_an_approver,self_approval; 404:not_found; 409:already_decided,already_voted,content_changed,expired,out_of_turn; 422:too_many_items; 428:reviewed_hash_required; 503:source_unavailable
GET /api/v1/approvals/inbox/{id}
Get one inbox
- Permission
api:access- Path parameters
id- Response
- 200: InboxDetail
- Errors
- 400:
no_organization,reason_required,scope_required,validation_error; 401:unauthorized; 403:not_an_approver,self_approval; 404:not_found; 409:already_decided,already_voted,content_changed,expired,out_of_turn; 422:too_many_items; 428:reviewed_hash_required; 503:source_unavailable
POST /api/v1/approvals/inbox/{id}/decision
Decision an inbox
- Permission
api:access- Path parameters
id- Request body
- object
- Response
- 200: InboxDetail
- Errors
- 400:
invalid_json,no_organization,reason_required,scope_required,validation_error; 401:unauthorized; 403:not_an_approver,person_required,self_approval,user_required; 404:not_found; 409:already_decided,already_voted,content_changed,expired,out_of_turn; 422:too_many_items; 428:reviewed_hash_required; 503:source_unavailable
GET /api/v1/approvals/metrics
List metrics
- Permission
approvals:read- Query parameters
from,org_id,to- Response
- 200: ApprovalMetrics
GET /api/v1/approvals/pending
The open requests the caller may see, filtered as the inbox filters them, never every request of the organization to any member.
- Permission
api:access- Query parameters
project_id- Response
- 200: ApprovalInfo
- Errors
- 400:
no_organization,project_mismatch; 401:unauthorized; 403:not_project_member; 404:project_not_found; 409:project_inactive; 503:projects_unavailable
GET /api/v1/approvals/poll
List poll
- Permission
api:access- Query parameters
action_hash- Response
- 200: object of string; 202: ApprovalRequest
GET /api/v1/approvals/recurring
Org_id defaults to the caller's organization.
- Permission
api:access- Query parameters
action_hash,org_id,user_id- Response
- 200: object of boolean
POST /api/v1/approvals/recurring
Create a recurring
- Permission
api:access- Request body
- object
- Response
- 201: object of string
- Errors
- 403:
person_required
POST /api/v1/approvals/redeem
Create a redeem
- Permission
none- Query parameters
token- Request body
- object
- Response
- 200: object of string
GET /api/v1/approvals/settings
List settings
- Permission
approvals:read- Response
- 200: Settings
- Errors
- 400:
no_organization,reason_required,scope_required,validation_error; 401:unauthorized; 403:not_an_approver,self_approval; 404:not_found; 409:already_decided,already_voted,content_changed,expired,out_of_turn; 422:too_many_items; 428:reviewed_hash_required; 503:source_unavailable
GET /api/v1/approvals/sla
List sla
- Permission
api:access- Query parameters
org_id- Response
- 200: ApprovalSLA
PUT /api/v1/approvals/sla
Set sla
- Permission
approvals:admin- Request body
- object
- Response
- 200: object of string
POST /api/v1/approvals/sla/process
(admin)
- Permission
approvals:admin- Response
- 200: object of integer
POST /api/v1/approvals/verify-token
Create a verify token
- Permission
api:access- Request body
- object
- Response
- object of string; 200: object of string
GET /api/v1/dlp/builtin-patterns
List builtin patterns
- Permission
dlp:read- Response
- 200: object of any
- Errors
- 401:
unauthorized; 403:forbidden
GET /api/v1/dlp/context-rules
List context rules
- Permission
dlp:read- Response
- 200: object of any
- Errors
- 401:
unauthorized; 503:service_unavailable
POST /api/v1/dlp/context-rules
Create a context rule
- Permission
dlp:manage- Request body
- ContextRule
- Response
- 201: ContextRule
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 403:person_required; 404:not_found; 415:content_type; 503:audit_unavailable,service_unavailable
DELETE /api/v1/dlp/context-rules/{id}
Delete one context rule
- Permission
dlp:manage- Path parameters
id- Response
- 200: object of any
- Errors
- 400:
validation_error; 401:unauthorized; 403:person_required; 404:not_found; 503:audit_unavailable,service_unavailable
POST /api/v1/dlp/detokenize
Create a detokenize
- Permission
dlp:detokenize- Request body
- object
- Response
- 200: object of any
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 415:content_type; 503:audit_unavailable,service_unavailable
GET /api/v1/dlp/enforcement
List enforcement
- Permission
dlp:read- Response
- 200: object of any
- Errors
- 401:
unauthorized; 403:forbidden
GET /api/v1/dlp/patterns
List patterns
- Permission
dlp:read- Response
- 200: object of any
- Errors
- 401:
unauthorized
POST /api/v1/dlp/patterns
Create a pattern
- Permission
dlp:manage- Request body
- object
- Response
- 201: object of any
- Errors
- 400:
invalid_json,pattern,validation_error; 401:unauthorized; 404:not_found; 415:content_type; 503:audit_unavailable
DELETE /api/v1/dlp/patterns/{id}
Delete one pattern
- Permission
dlp:manage- Path parameters
id- Response
- 200: object of any
- Errors
- 400:
validation_error; 401:unauthorized; 403:person_required; 404:not_found; 500:pattern; 503:audit_unavailable
POST /api/v1/dlp/scan
Create a scan
- Permission
api:access- Request body
- object
- Response
- 200: ExtendedScanResult
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 415:content_type; 503:service_unavailable
GET /api/v1/dlp/stats
List stats
- Permission
dlp:read- Response
- 200: object of any
- Errors
- 401:
unauthorized
POST /api/v1/dlp/tokenize
Create a tokenize
- Permission
api:access- Request body
- object
- Response
- 200: object of any
- Errors
- 400:
invalid_json,validation_error; 401:unauthorized; 415:content_type; 503:dlp_token_key_unavailable,service_unavailable
GET /api/v1/dlp/violations
The caller's organization's violations, newest first. type keeps one pattern type and tool the violations whose tool_name equals it exactly (1 to 128 printable characters); both are applied before the limit.
- Permission
dlp:read- Query parameters
tool,type- Response
- 200: object of any
- Errors
- 400:
invalid_query; 401:unauthorized
POST /api/v1/dlp/violations/{id}/false-positive
False positive a violation
- Permission
dlp:manage- Path parameters
id- Response
- 200: object of any
- Errors
- 400:
validation_error; 401:unauthorized; 403:own_violation,person_required; 404:not_found; 500:violation; 503:audit_unavailable
GET /api/v1/orgs/{orgID}/governance/killswitch
List killswitch
- Permission
api:access- Path parameters
orgID- Response
- 200: KillSwitch
- Errors
- 400:
invalid_org_id; 503:governance_store_unavailable
PUT /api/v1/orgs/{orgID}/governance/killswitch
Turns the organization's workspace kill switch on or off (governance:manage). The change and its audit entry commit together.
- Permission
governance:manage- Path parameters
orgID- Request body
- govSetKillSwitchRequest
- Response
- 200: object of any
- Errors
- 400:
confirmation_mismatch,invalid_json,invalid_org_id; 403:person_required,step_up_failed,step_up_required; 415:content_type; 500:kill_switch_partial; 503:audit_unavailable,governance_store_unavailable,unavailable
Objects
object
| Field | Type | Description |
|---|---|---|
org_id | string | |
channel_type | string | |
config | JSON |
object
| Field | Type | Description |
|---|---|---|
decision | string | |
reason | string | |
scope | string | |
reviewed_hash | string |
object
| Field | Type | Description |
|---|---|---|
org_id | string | |
user_id | string | |
action_hash | string | |
approval_id | string | |
duration_hours | integer |
object
| Field | Type | Description |
|---|---|---|
token | string | |
decision | string | |
comment | string |
object
| Field | Type | Description |
|---|---|---|
token | string |
object
| Field | Type | Description |
|---|---|---|
ttl_minutes | integer |
object
| Field | Type | Description |
|---|---|---|
ttl_minutes | integer |
object
| Field | Type | Description |
|---|---|---|
decision | string | |
comment | string |
object
| Field | Type | Description |
|---|---|---|
token | string |
object
| Field | Type | Description |
|---|---|---|
name | string | |
pattern_type | string | |
pattern | string | |
action | string |
object
| Field | Type | Description |
|---|---|---|
text | string | |
agent_role | string | |
destination | string |
object
| Field | Type | Description |
|---|---|---|
value | string |
object
| Field | Type | Description |
|---|---|---|
org_id | string | |
sla | ApprovalSLA |
ApprovalInfo
The payload sent via notification channels.
| Field | Type | Description |
|---|---|---|
id | string | |
agent_id | string | |
session_id | string | |
action | string | |
resource | string | |
params | JSON | |
expires_at | timestamp | |
created_at | timestamp | |
project_id optional | string |
ApprovalMetrics
ApprovalMetrics holds aggregate statistics for a time window.
| Field | Type | Description |
|---|---|---|
org_id | string | |
from | timestamp | |
to | timestamp | |
total_approved | integer | |
total_rejected | integer | |
total_pending | integer | |
sla_violations | integer | |
avg_decision_time_secs | number | |
auto_approved | integer |
ApprovalRequest
The full data model for an approval request.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | The request's NRN; the API handler sets it, and a client's value is never stored. |
org_id | string | |
subject_type optional | string | |
subject_id optional | string | |
agent_id | string | |
session_id | string | |
user_id optional | string | |
action | string | |
resource | string | |
params | JSON | |
reason optional | string | |
status | string | |
approval_type | string | |
approver_group optional | string | |
quorum_required | integer | |
quorum_total | integer | |
action_hash optional | string | |
sla_warn_mins | integer | |
sla_escalate_mins | integer | |
sla_reject_mins | integer | |
sla_escalation_group optional | string | |
conditions optional | JSON | |
approvers optional | array of string | The ordered approver sequence of a sequential request: user IDs, each of whom must approve in turn. Required for TypeSequential, ignored otherwise. |
valid_for_mins | integer | ValidForMins bounds how long an approved request stays valid after its decision; 0 means it does not lapse. |
escalated_at optional | timestamp | |
escalation_count | integer | |
decided_by optional | string | |
decided_at optional | timestamp | |
expires_at | timestamp | |
created_at | timestamp | |
project_id optional | string | The Directory project the request gates; "" for an account-level request. The database refuses a project of another organization. |
requester_api_key_id optional | string | The API key that filed the request through the public API, set by Sandscale from the authenticated principal (never from the body). The key's owner is the requester, so nobody approves what they asked for through their own key, and only that key or that person reads the request's outcome by action hash. |
ApprovalSLA
The persisted, org-level SLA configuration. It maps to approval_sla_configs and is applied to new requests unless overridden per-request.
| Field | Type | Description |
|---|---|---|
warn_after_mins | integer | |
escalate_after_mins | integer | |
auto_reject_after_mins | integer | |
escalation_target_group | string |
ChannelField
One setting of a channel type.
| Field | Type | Description |
|---|---|---|
name | string | |
label | string | |
hint optional | string | |
secret | boolean | |
required | boolean |
ChannelSummary
An approval channel without its secrets, with its last delivery.
| Field | Type | Description |
|---|---|---|
id | string | |
type | string | |
type_label | string | |
destination | string | |
enabled | boolean | |
created_at | timestamp | |
last_status optional | string | |
last_error optional | string | |
last_sent_at optional | timestamp |
ChannelType
A kind of approval channel and its settings.
| Field | Type | Description |
|---|---|---|
type | string | |
label | string | |
fields | array of ChannelField |
GrantScope
A choice a source offers with an approval.
| Field | Type | Description |
|---|---|---|
value | string | |
label | string |
InboxDetail
A request with its votes, notifications and parameters.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | The request's NRN; the API handler sets it. |
source | string | |
source_label | string | |
title | string | |
action | string | |
resource | string | |
agent_id optional | string | |
requester_id optional | string | |
requester_email optional | string | |
project_id optional | string | |
status | string | |
status_label | string | |
open | boolean | True while the request waits for a decision (pending or escalated). |
approval_type | string | |
type_label | string | |
approvals | integer | |
approvals_needed | integer | |
approver_group optional | string | |
created_at | timestamp | |
expires_at optional | timestamp | When an open request expires; zero (left out) for a source whose requests do not expire. |
decided_by optional | string | |
decided_by_email optional | string | |
decided_at optional | timestamp | |
decision_reason optional | string | |
sla optional | InboxSLA | The request's SLA state; nil for a source without SLA thresholds. |
can_decide | boolean | Whether the viewer's vote would be accepted now; CannotDecide says why not when it would not. |
cannot_decide optional | string | |
decide_on optional | string | DecideOn says where the viewer decides when CanDecide is set: DecideOnInbox (this inbox's decision route), DecideOnGrantPage (a vault grant, approved with a passkey on its own page) or DecideOnFilePage (an agent instruction file version, approved on the review page after reading it). Empty when the viewer cannot decide. |
is_requester | boolean | Set by the server when the viewer filed the request. |
grant_scopes optional | array of GrantScope | The choices an approval of this request takes (an agent permission is granted once or for the session); empty when it takes none. |
reason optional | string | |
params | JSON | |
votes | array of InboxVote | |
dispatches | array of InboxDispatch | |
review_hash optional | string | ReviewHash names exactly what an approval of this request approves, for a source whose approval binds to reviewed content (an agent file version's content SHA-256); the approver sends it back as InboxDecision.ReviewedHash. Empty for every other source. |
InboxDispatch
One notification sent for a request.
| Field | Type | Description |
|---|---|---|
channel_type | string | |
channel_label | string | |
status | string | |
error optional | string | |
dispatched_at | timestamp |
InboxItem
One approval request as the inbox shows it to a viewer.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | The request's NRN; the API handler sets it. |
source | string | |
source_label | string | |
title | string | |
action | string | |
resource | string | |
agent_id optional | string | |
requester_id optional | string | |
requester_email optional | string | |
project_id optional | string | |
status | string | |
status_label | string | |
open | boolean | True while the request waits for a decision (pending or escalated). |
approval_type | string | |
type_label | string | |
approvals | integer | |
approvals_needed | integer | |
approver_group optional | string | |
created_at | timestamp | |
expires_at optional | timestamp | When an open request expires; zero (left out) for a source whose requests do not expire. |
decided_by optional | string | |
decided_by_email optional | string | |
decided_at optional | timestamp | |
decision_reason optional | string | |
sla optional | InboxSLA | The request's SLA state; nil for a source without SLA thresholds. |
can_decide | boolean | Whether the viewer's vote would be accepted now; CannotDecide says why not when it would not. |
cannot_decide optional | string | |
decide_on optional | string | DecideOn says where the viewer decides when CanDecide is set: DecideOnInbox (this inbox's decision route), DecideOnGrantPage (a vault grant, approved with a passkey on its own page) or DecideOnFilePage (an agent instruction file version, approved on the review page after reading it). Empty when the viewer cannot decide. |
is_requester | boolean | Set by the server when the viewer filed the request. |
grant_scopes optional | array of GrantScope | The choices an approval of this request takes (an agent permission is granted once or for the session); empty when it takes none. |
InboxPage
A page of the inbox.
| Field | Type | Description |
|---|---|---|
view | string | |
source optional | string | The source filter of the page, "" for every source. |
sources | array of InboxSourceInfo | What the inbox can be filtered by. |
scope | string | "organization" when the page lists every request of the organization, or "mine" when it lists only those visible to the viewer (no approvals:read). A "mine" page may hold fewer items than the limit and still carry a next_cursor. |
items | array of InboxItem | |
next_cursor optional | string | |
summary | InboxSummary | |
relation optional | string | The relation filter of the page, "" for none. |
InboxSLA
A request's SLA state: its thresholds as times and where it stands.
| Field | Type | Description |
|---|---|---|
state | string | |
label | string | |
warn_at | timestamp | |
escalate_at | timestamp | |
reject_at | timestamp | |
next_label optional | string | |
next_at optional | timestamp |
InboxSourceInfo
InboxSourceInfo names a source the inbox can be filtered by.
| Field | Type | Description |
|---|---|---|
key | string | |
label | string |
InboxSummary
InboxSummary counts the organization's open requests by SLA state.
| Field | Type | Description |
|---|---|---|
open | integer | |
warning | integer | |
escalation_due | integer | |
escalated | integer | |
overdue | integer | |
to_decide_on_page | integer | |
matching | integer | Matching counts every request of the relation the page belongs to, whatever the page limit (open and decided); 0 for a page without a relation. For such a page Open and the SLA counts are those of the relation's open requests. |
InboxVote
One vote on a request.
| Field | Type | Description |
|---|---|---|
approver_id | string | |
approver_email optional | string | |
decision | string | |
decision_label | string | |
comment optional | string | |
voted_at | timestamp |
SLASettings
The organization's SLA as the settings show it.
| Field | Type | Description |
|---|---|---|
warn_after_mins | integer | |
escalate_after_mins | integer | |
auto_reject_after_mins | integer | |
escalation_target_group | string | |
configured | boolean | False when the organization uses DefaultSLA. |
max_minutes | integer |
Settings
The organization's approval configuration: its SLA and its channels.
| Field | Type | Description |
|---|---|---|
sla | SLASettings | |
channels | array of ChannelSummary | |
channel_types | array of ChannelType |
ContextRule
ContextRule defines a policy: for a given (agent_role, data_class, destination) triple, enforce the specified action. Wildcards ("*") are supported in all three dimensions.
| Field | Type | Description |
|---|---|---|
id | string | |
nrn optional | string | The rule's NRN; the API handler sets it. |
org_id | string | |
agent_role | string | |
data_class | string | |
destination | string | |
action | string | Block | redact | tokenize | alert | allow |
reason | string | |
priority | integer | Lower number = higher priority |
created_at | timestamp |
ExtendedScanResult
The output of ScanText; richer than the base ScanResult.
| Field | Type | Description |
|---|---|---|
HasViolation | boolean | True when at least one pattern matched. |
Violations | array of Violation | Violations lists every individual match. |
RedactedText | string | The input text with every match replaced by [REDACTED:<type>]. With no match it is the input text. |
classification optional | string | The strictest classification among Violations; empty when nothing matched. No finding does not make text public, so callers keep their own classification in that case. |
org_id | string | |
agent_role | string | |
destination | string | |
context_action optional | string | The action dictated by the matching context rule (if any). When empty, no context rule matched and pattern-level actions apply. |
context_reason optional | string | |
tokenization_failed optional | boolean | Set when a span due for tokenization could not be stored in the vault and was redacted instead. |
Violation
Violation describes a single match found during a scan.
| Field | Type | Description |
|---|---|---|
PatternName | string | |
PatternType | string | |
MatchStart | integer | |
MatchEnd | integer | |
Action | string | Block | warn | redact | log_only |
classification optional | string | The context classification level of the matched data. |
KillSwitch
KillSwitch represents the state of the kill switch for an org.
| Field | Type | Description |
|---|---|---|
org_id | uuid | |
active | boolean | |
reason optional | string | |
updated_at | timestamp | |
org_kill_switch_engaged | boolean | The organization kill switch (the AI SOC or endpoint switch), which stops and refuses workspaces too; OrgKillSwitchSources names what engaged it. |
org_kill_switch_sources optional | array of string | |
engaged | boolean | The server's answer: the organization's workspaces are refused and stopped. |
govSetKillSwitchRequest
| Field | Type | Description |
|---|---|---|
active | boolean | |
reason optional | string | |
confirm_account_name optional | string | |
mfa_code 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.