POST /sdk/check

Overview

The check endpoint validates whether an agent has permission to perform a specific action. This is the primary permission validation endpoint used by the SDK.

Authentication

X-API-Key

string

required

Your organization’s API key

Request Body

agent_id

string

required

Unique identifier of the agent performing the action

action

string

required

The action identifier (e.g., “stripe.refund”, “email.send”)

context

object

Additional context for the permission check. Used for validating limits like max_amount.

Example Request

curl -X POST https://api.agentwarden.io/sdk/check \
  -H "X-API-Key: ak_1234567890abcdefghij" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "action": "stripe.refund",
    "context": {
      "amount": 50.00,
      "customer_id": "cus_ABC123",
      "reason": "defective_product"
    }
  }'

Response

allowed

boolean

required

Whether the action is allowed to proceed

requires_approval

boolean

required

Whether human approval is required before executing the action

reason

string | null

Explanation if the action is blocked or requires approval

approval_id

string | null

Unique ID of the approval request (only present if requires_approval is true)

Success Response - Allowed

{
  "allowed": true,
  "requires_approval": false,
  "reason": null,
  "approval_id": null
}

Success Response - Requires Approval

{
  "allowed": false,
  "requires_approval": true,
  "reason": "This action requires human approval",
  "approval_id": "apr_xyz789abc123"
}

Success Response - Blocked

{
  "allowed": false,
  "requires_approval": false,
  "reason": "Amount 150.00 exceeds maximum allowed 100.00",
  "approval_id": null
}

Response Scenarios

✅ Permission Granted

The agent has permission and can proceed immediately:

{
  "allowed": true,
  "requires_approval": false,
  "reason": null,
  "approval_id": null
}

Next steps: Execute the action and log the result.

⏳ Approval Required

The agent has permission but needs human approval first:

{
  "allowed": false,
  "requires_approval": true,
  "reason": "This action requires human approval",
  "approval_id": "apr_xyz789abc123"
}

Next steps:

Notify administrator with approval_id
Wait for approval decision
Check approval status or use webhooks

🚫 Permission Denied

The action is not allowed for one of several reasons:

No Permission
Exceeds Limit
Agent Inactive
Agent Not Found

    {
      "allowed": false,
      "requires_approval": false,
      "reason": "No permission found for action 'stripe.refund'",
      "approval_id": null
    }

    {
      "allowed": false,
      "requires_approval": false,
      "reason": "Amount 500.00 exceeds maximum allowed 100.00",
      "approval_id": null
    }

    {
      "allowed": false,
      "requires_approval": false,
      "reason": "Agent is not active (status: inactive)",
      "approval_id": null
    }

    {
      "allowed": false,
      "requires_approval": false,
      "reason": "Agent '550e8400-e29b-41d4-a716-446655440000' not found",
      "approval_id": null
    }

Next steps: Handle the denial appropriately (notify user, log, etc.)

Error Responses

401 Unauthorized

Invalid or missing API key:

{
  "detail": "Invalid API key"
}

400 Bad Request

Missing or invalid parameters:

{
  "detail": {
    "agent_id": ["This field is required"],
    "action": ["This field is required"]
  }
}

429 Too Many Requests

Rate limit exceeded:

{
  "detail": "Rate limit exceeded. Please try again in 60 seconds."
}

Response Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000060
Retry-After: 60

Context Validation

The context object is used to validate permissions with limits:

Amount Validation

If a permission has max_amount set, include the amount in context:

{
  "agent_id": "bot-123",
  "action": "stripe.refund",
  "context": {
    "amount": 50.00  // Will be checked against max_amount
  }
}

Custom Context

Include any additional data that helps with approval decisions:

{
  "agent_id": "bot-123",
  "action": "database.delete",
  "context": {
    "table": "users",
    "record_count": 1,
    "user_id": "usr_abc123",
    "reason": "GDPR deletion request",
    "ticket_id": "TICKET-4567"
  }
}

This context will be visible to approvers if the action requires approval.

Best Practices

1. Always Check Before Acting

Call the check endpoint before every action, even if you think it’s allowed. Permissions can change.

    # ✅ Good
    result = check_permission(agent_id, action, context)
    if result['allowed']:
        execute_action()
    
    # ❌ Bad - assuming permission exists
    execute_action()  # No check!

2. Provide Rich Context

Include all relevant information in the context object:

    # ✅ Good - rich context
    context = {
        "amount": 50.00,
        "customer_id": "cus_123",
        "customer_email": "john@example.com",
        "order_id": "ord_456",
        "reason": "defective_product",
        "ticket_url": "https://zendesk.com/12345"
    }
    
    # ❌ Bad - minimal context
    context = {"amount": 50.00}

3. Handle All Response Scenarios

Your code should handle allowed, requires_approval, and denied cases:

    result = check_permission(agent_id, action, context)
    
    if result['allowed']:
        # Execute immediately
        execute_action()
        log_action("success")
    
    elif result['requires_approval']:
        # Queue for approval
        approval_id = result['approval_id']
        notify_admin(approval_id)
        queue_action(approval_id)
    
    else:
        # Handle denial
        log_action("denied", reason=result['reason'])
        notify_user(result['reason'])

4. Implement Retry Logic

Network errors can happen - implement retry with exponential backoff:

    import time
    
    def check_with_retry(agent_id, action, context, max_retries=3):
        for attempt in range(max_retries):
            try:
                return check_permission(agent_id, action, context)
            except NetworkError:
                if attempt < max_retries - 1:
                    time.sleep(2 ** attempt)
                else:
                    raise

5. Cache Wisely (Optional)

For identical actions, you can cache check results briefly:

    from functools import lru_cache
    import hashlib
    
    @lru_cache(maxsize=1000)
    def cached_check(agent_id, action, context_hash):
        # TTL: implement cache expiration
        return check_permission(agent_id, action, context)
    
    # Use with caution - permissions can change!

Common Use Cases

E-commerce Refunds

curl -X POST https://api.agentwarden.io/sdk/check \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "customer-support-bot",
    "action": "stripe.refund",
    "context": {
      "amount": 75.00,
      "customer_id": "cus_ABC123",
      "order_id": "ord_XYZ789",
      "reason": "damaged_product"
    }
  }'

Database Operations

curl -X POST https://api.agentwarden.io/sdk/check \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "data-cleanup-bot",
    "action": "database.users.delete",
    "context": {
      "user_id": "usr_123",
      "reason": "gdpr_request",
      "ticket_id": "GDPR-4567"
    }
  }'

Deployment Actions

curl -X POST https://api.agentwarden.io/sdk/check \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "devops-agent",
    "action": "deploy.production",
    "context": {
      "version": "v2.1.0",
      "environment": "production",
      "commit": "a1b2c3d",
      "tests_passed": true
    }
  }'

Rate Limiting

This endpoint is rate limited. See response headers for current limits:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Rate limits by plan:

Free: 100 requests/minute
Pro: 1,000 requests/minute
Business: 10,000 requests/minute
Enterprise: Custom

Log Action

Log the action after execution

Get Approval Status

Check status of approval request

Python SDK

Use the SDK instead of direct API calls

Permissions

Learn about permission configuration

API Documentation

Endpoints

Overview

Authentication

Request Body

Example Request

Response

Success Response - Allowed

Success Response - Requires Approval

Success Response - Blocked

Response Scenarios

✅ Permission Granted

⏳ Approval Required

🚫 Permission Denied

Error Responses

401 Unauthorized

400 Bad Request

429 Too Many Requests

Context Validation

Amount Validation

Custom Context

Best Practices

Common Use Cases

E-commerce Refunds

Database Operations

Deployment Actions

Rate Limiting

Log Action

Get Approval Status

Python SDK

Permissions

API Documentation

Endpoints

​Overview

​Authentication

​Request Body

​Example Request

​Response

​Success Response - Allowed

​Success Response - Requires Approval

​Success Response - Blocked

​Response Scenarios

​✅ Permission Granted

​⏳ Approval Required

​🚫 Permission Denied

​Error Responses

​401 Unauthorized

​400 Bad Request

​429 Too Many Requests

​Context Validation

​Amount Validation

​Custom Context

​Best Practices

​Common Use Cases

​E-commerce Refunds

​Database Operations

​Deployment Actions

​Rate Limiting

​Related Endpoints

Log Action

Get Approval Status

Python SDK

Permissions

Overview

Authentication

Request Body

Example Request

Response

Success Response - Allowed

Success Response - Requires Approval

Success Response - Blocked

Response Scenarios

✅ Permission Granted

⏳ Approval Required

🚫 Permission Denied

Error Responses

401 Unauthorized

400 Bad Request

429 Too Many Requests

Context Validation

Amount Validation

Custom Context

Best Practices

Common Use Cases

E-commerce Refunds

Database Operations

Deployment Actions

Rate Limiting

Related Endpoints