Actions and policy API

GET /api/v1/actions

Read non-archived action definitions in this environment.

Credential: Server credential.

Inputs: No body or pagination parameters; the list contains at most 500 non-archived actions.

Effect and retry behavior: Read-only bounded list. Use the returned record id for action administration and the key for authorization.

Responses

Response handling: An empty list means the query returned no visible registered actions. Register and configure the intended action before authorization.

Example

GET /api/v1/actions

[
  {
    "id": "act_example",
    "key": "payout.destination.change",
    "mode": "shadow"
  }
]

POST /api/v1/actions

Create an action definition and its initial active policy in shadow mode.

Credential: Admin server credential.

Inputs: Supply a dotted key, display name, consequence and nonempty allowed_audiences. Use context_schema to bind sensitive business fields.

Effect and retry behavior: Creates a new action and initial policy in shadow mode. Defaults include risk_class high and proof_ttl_seconds 300. Configure the action mode separately.

Request body

application/json; required. ActionCreate.

Responses

Response handling: Conflicting keys, invalid context schemas and unsupported settings are refused. Read existing configuration before retrying a create after a timeout.

Example

POST /api/v1/actions

{
  "key": "payout.destination.change",
  "name": "Change payout destination",
  "consequence": "Future payouts may be sent to a different destination.",
  "resource_type": "merchant",
  "allowed_audiences": [
    "merchant-api"
  ],
  "context_schema": {
    "type": "object",
    "properties": {
      "destination_fingerprint": {
        "type": "string"
      }
    },
    "required": [
      "destination_fingerprint"
    ],
    "additionalProperties": false
  }
}

{
  "id": "act_example",
  "key": "payout.destination.change",
  "mode": "shadow",
  "active_policy_version": 1
}

DELETE /api/v1/actions/{action_id}

Stop using an action through the normal active action surface while retaining its historical records.

Credential: Admin server credential.

Inputs: Action record id only.

Effect and retry behavior: Archives the action. Historical authorizations and policies are not rewritten; integrations must handle subsequent refusal.

Parameters

Responses

Response handling: Missing or unavailable actions are refused. Reconcile uncertain archive responses through action state before accepting new business requests.

Example

DELETE /api/v1/actions/act_example

HTTP 204; no response body.

GET /api/v1/actions/{action_id}

Inspect the action’s display metadata, mode and active policy settings before integration or a configuration change.

Credential: Server credential.

Inputs: Use the action record id, not its key.

Effect and retry behavior: Read-only; compare active_policy_version when reviewing changes.

Parameters

Responses

Response handling: 404 for missing, archived or out-of-scope actions.

Example

GET /api/v1/actions/act_example

{
  "id": "act_example",
  "key": "payout.destination.change",
  "mode": "shadow",
  "active_policy_version": 1
}

PATCH /api/v1/actions/{action_id}

Change an action’s customer-facing name, consequence or test/shadow/enforce mode.

Credential: Admin server credential.

Inputs: Omit fields that should remain unchanged. Change audiences, caller restrictions, context or proof lifetime through a new policy version.

Effect and retry behavior: Updates the supplied action metadata or mode. Read the returned mode to confirm the effective configuration.

Parameters

Request body

application/json; required. ActionUpdate.

Responses

Response handling: For error.enforcement_not_approved, retain the effective mode and confirm the environment configuration with GrayPass. Action display metadata and immutable policy versions are configured separately.

Example

PATCH /api/v1/actions/act_example

{
  "name": "Change merchant payout destination"
}

{
  "id": "act_example",
  "key": "payout.destination.change",
  "mode": "shadow"
}

GET /api/v1/actions/{action_id}/policy-versions

Inspect the action’s immutable draft, active and retired policy snapshots.

Credential: Server credential.

Inputs: Action record id only; no pagination cursor.

Effect and retry behavior: Read-only. Only the active version controls new decisions.

Parameters

Responses

Response handling: 404 for an unavailable action. Use the active policy version for a new authorization.

Example

GET /api/v1/actions/act_example/policy-versions

[
  {
    "id": "pol_example",
    "action": "act_example",
    "version": 1,
    "status": "active"
  }
]

POST /api/v1/actions/{action_id}/policy-versions

Prepare a new immutable policy snapshot without activating it.

Credential: Admin server credential.

Inputs: requirements is required. Omitted optional audiences, caller restrictions, context schema and proof lifetime inherit from the active version.

Effect and retry behavior: Creates a numbered draft; existing authorizations retain their original snapshot. Activate explicitly after review.

Parameters

Request body

application/json; required. PolicyVersionCreate.

Responses

Response handling: Invalid claim requirements, challenge methods, audiences or context schema are refused. A retry can create another draft; list versions after uncertainty.

Example

POST /api/v1/actions/act_example/policy-versions

{
  "requirements": {
    "coverage_min": "partial",
    "freshness_max_ms": 60000,
    "insufficient_evidence": "challenge",
    "challenge_methods": [
      "passkey"
    ]
  }
}

{
  "id": "pol_example",
  "action": "act_example",
  "version": 2,
  "status": "draft"
}

POST /api/v1/actions/{action_id}/policy-versions/{version}/activate

Select an existing version as the action’s active decision contract.

Credential: Admin server credential.

Inputs: Action record id and integer version number. Review the whole draft snapshot before activating.

Effect and retry behavior: Activates the selected version and retires the prior active version. Pending/retried authorization can fail as stale rather than silently changing meaning.

Parameters

Responses

Response handling: Unavailable or incompatible versions and lifecycle conflicts are refused; read the active version after an uncertain response.

Example

POST /api/v1/actions/act_example/policy-versions/2/activate

{
  "id": "pol_example",
  "action": "act_example",
  "version": 2,
  "status": "active"
}