Policy APIs

Policies allow you to define and enforce rules for requests made through your connections. Each policy consists of a type (what to check for) and an action (what to do when the policy is triggered).

Required Headers

All API endpoints require these headers:

Name
Authorization
Type
string
Description
Bearer token for authentication. Format: 'Bearer your-token-here'
Name
traceparent
Type
string
Description
OpenTelemetry trace parent for distributed tracing
Name
tracestate
Type
string
Description
OpenTelemetry trace state information

GET/v1/management/policies

List Available Policies

Get a list of all available policy types and their valid actions. Use this to understand what policies you can configure.

Response Properties

Name
policyType
Type
string
Description
The type identifier for the policy
Name
validActions
Type
array
Description
List of actions that can be taken when the policy is triggered
Name
description
Type
string
Description
Detailed description of what the policy does
Name
isEnabled
Type
boolean
Description
Whether this policy type is currently available for use

Request

GET

/v1/management/policies

curl -X GET https://api.usageguard.com/v1/management/policies \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}"

Response

{
  "items": [
    {
      "policyType": "content_filtering",
      "validActions": ["block", "audit"],
      "description": "Filters content based on predefined rules",
      "isEnabled": true
    },
    {
      "policyType": "pii_detection",
      "validActions": ["redact", "block", "audit"],
      "description": "Detects and handles Personally Identifiable Information",
      "isEnabled": true
    }
  ]
}

401: Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

403: Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions to access policies"
}

GET/v1/management/connections/{connectionId}/policies

List Connection Policies

Get all policies configured for a specific connection. Use this to review your connection's security and compliance settings.

Path Parameters

Name
connectionId
Type
string
Description
The ID of the connection to get policies for

Response Properties

Name
policyId
Type
string
Description
Unique identifier for the policy
Name
type
Type
string
Description
The type of policy
Name
action
Type
string
Description
The action taken when policy is triggered
Name
disabled
Type
boolean
Description
Whether the policy is currently disabled
Name
created
Type
string
Description
When the policy was created
Name
updated
Type
string
Description
When the policy was last updated
Name
configuration
Type
object
Description
Policy-specific configuration settings

Request

GET

/v1/management/connections/{connectionId}/policies

curl -X GET https://api.usageguard.com/v1/management/connections/conn_abc123/policies \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}"

Response

{
  "items": [
    {
      "policyId": "pol_xyz789",
      "type": "content_filtering",
      "action": "block",
      "disabled": false,
      "created": "2024-03-15T10:30:00Z",
      "updated": "2024-03-15T10:30:00Z",
      "configuration": {
        "sensitivityLevel": "high"
      }
    }
  ]
}

401: Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

403: Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions to access this connection's policies"
}

404: Not Found

{
  "error": "Not Found",
  "message": "Connection not found. Verify the connection ID and ensure you have access to it"
}

POST/v1/management/connections/{connectionId}/policies

Create Policy

Create a new policy for a specific connection. Use this to add security and compliance rules to your connection.

Path Parameters

Name
connectionId
Type
string
Description
The ID of the connection to create the policy for

Request Body

Name
type
Type
string
Description
The type of policy to create (from available policy types)
Name
action
Type
string
Description
The action to take when policy is triggered (must be valid for the policy type)
Name
configuration
Type
object
Description
Policy-specific configuration settings

Request

POST

/v1/management/connections/{connectionId}/policies

curl -X POST https://api.usageguard.com/v1/management/connections/conn_abc123/policies \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "content_filtering",
    "action": "block",
    "configuration": {
      "sensitivityLevel": "high"
    }
  }'

Response

{
  "policyId": "pol_xyz789",
  "type": "content_filtering",
  "action": "block",
  "disabled": false,
  "created": "2024-03-15T10:30:00Z",
  "updated": "2024-03-15T10:30:00Z",
  "configuration": {
    "sensitivityLevel": "high"
  }
}

400: Bad Request

{
  "error": "Bad Request",
  "message": "Invalid policy type or action. Check available policy types for valid options."
}

PUT/v1/management/connections/{connectionId}/policies/{policyId}

Update Policy

Update an existing policy's configuration. Use this to modify the behavior of your security and compliance rules.

Path Parameters

Name
connectionId
Type
string
Description
The ID of the connection containing the policy
Name
policyId
Type
string
Description
The ID of the policy to update

Request Body

Name
action
Type
string
Description
The new action to take when policy is triggered
Name
disabled
Type
boolean
Description
Whether to disable the policy
Name
configuration
Type
object
Description
Updated policy-specific configuration settings

Request

PUT

/v1/management/connections/{connectionId}/policies/{policyId}

curl -X PUT https://api.usageguard.com/v1/management/connections/conn_abc123/policies/pol_xyz789 \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "audit",
    "disabled": false,
    "configuration": {
      "sensitivityLevel": "medium"
    }
  }'

Response

{
  "policyId": "pol_xyz789",
  "type": "content_filtering",
  "action": "audit",
  "disabled": false,
  "created": "2024-03-15T10:30:00Z",
  "updated": "2024-03-15T11:45:00Z",
  "configuration": {
    "sensitivityLevel": "medium"
  }
}

404: Not Found

{
  "error": "Not Found",
  "message": "Policy not found. Verify the policy ID and connection ID."
}

DELETE/v1/management/connections/{connectionId}/policies/{policyId}

Delete Policy

Permanently delete a policy from a connection. Warning: This action cannot be undone.

Path Parameters

Name
connectionId
Type
string
Description
The ID of the connection containing the policy
Name
policyId
Type
string
Description
The ID of the policy to delete

Request

DELETE

/v1/management/connections/{connectionId}/policies/{policyId}

curl -X DELETE https://api.usageguard.com/v1/management/connections/conn_abc123/policies/pol_xyz789 \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}"

Response

{
  "status": "success",
  "message": "Policy deleted successfully"
}

404: Not Found

{
  "error": "Not Found",
  "message": "Policy not found. Verify the policy ID and connection ID."
}

403: Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions to delete this policy"
}