AI-Powered Security Analysis for AWS

API Reference

Full REST API for programmatic, AI-Powered analysis of AWS IAM policies, CloudFormation templates, and costs. Base URL: https://api.shieldly.io

Authentication

All API calls require a Bearer token in the Authorization header. Generate an API key from the API panel in your dashboard. Keys draw from your daily unit allowance and support PAYG overage when enabled.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Rate Limits

Plan	Daily Units
Free	20
Builder	150
Pro	300
Team	600

Units reset at midnight UTC. PAYG extends beyond the cap at $0.09/unit when enabled. When the daily cap is hit, the API returns 429 Too Many Requests.

Endpoints

POST/v1/analyze/iam

Analyze an IAM identity policy or cross-account trust policy.

Field	Type	Required	Notes
policy	string	yes	JSON-encoded IAM policy
policyType	string	no	iam_identity (default) or cross_account. Other IAM/resource policy JSON is accepted as iam_identity; cross_account expects {identityPolicy, trustPolicy}.

Request

{
  "policy": "{\"Version\":\"2012-10-17\",\"Statement\":[...]}",
  "policyType": "iam_identity"
}

Response

{
  "score": 42,
  "riskLevel": "High",
  "findings": [
    {
      "severity": "Critical",
      "title": "Wildcard action on all resources",
      "description": "The policy grants Action: * on Resource: *",
      "resource": "Resource: *",
      "remediation": "Replace * with specific actions and scope resources to exact ARNs."
    }
  ],
  "aiGrade": "Standard AI",
  "unitInfo": { "multiplier": 1, "inputSize": "340 chars", "unitsUsed": 1, "cap": 20 }
}

Input size limits

Size	Units
0–1,200 chars	1×
1,201–3,000 chars	2×
3,001–6,000 chars	3×
6,001–12,000 chars	5×
12,001–25,000 chars	8×
> 25,000 chars	413 Rejected

POST/v1/analyze/cf

Analyze a CloudFormation template. Builder+ plan required.

Request

{
  "template": "<raw CloudFormation JSON or YAML string>"
}

Response

// Same shape as /v1/analyze/iam, plus:
{
  "resourceCount": 12,
  "templateSize": "42.1 KB"
}

File size limits

Size	Units
< 25 KB	5×
25–100 KB	10×
100–300 KB	20×
300–600 KB	30×
> 600 KB	413 Rejected

POST/v1/analyze/cost

Analyze AWS cost data. Builder+ plan required.

Request

{
  "costData": "<CSV or JSON cost export from AWS Cost Explorer>"
}

GET/v1/usage

Get current daily usage for the authenticated user.

Response

{
  "unitsUsed": 7,
  "unitsRemaining": 13,
  "cap": 20,
  "plan": "free",
  "resetAt": "2026-05-22T00:00:00.000Z"
}

GET/v1/analyses

List past analysis history. Builder+ plan required.

Query params: limit (default 20, max 50), before (timestamp cursor for pagination)

Response

{
  "analyses": [
    {
      "analysisId": "user123-1716422400000",
      "type": "iam_identity",
      "units": 1,
      "multiplier": 1,
      "cached": false,
      "payg": false,
      "aiGrade": "Standard AI",
      "source": "api",
      "timestamp": "2026-05-22T12:00:00.000Z"
    }
  ],
  "nextCursor": null,
  "plan": "builder",
  "retentionDays": 30
}

GET/v1/api-keys

List API keys for the authenticated user.

POST/v1/api-keys

Generate a new API key. Returns the raw key once — store it immediately.

Response

{
  "apiKey": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  "keyId": "key_xxxxxxxxxxxx",
  "createdAt": "2026-05-22T12:00:00.000Z"
}

DELETE/v1/api-keys/{id}

Revoke an API key.

GET/v1/settings/payg

Get PAYG (pay-as-you-go) overage settings.

PATCH/v1/settings/payg

Update PAYG settings. hardCap options: 5, 10, 25, 50, 100, null (unlimited).

Request

{
  "enabled": true,
  "hardCap": 25
}

Error Codes

Code	Meaning
400	Bad request — invalid JSON or missing required field
401	Unauthorized — missing or invalid API key
403	Forbidden — plan does not include this endpoint
413	Input too large — reduce policy or template size
429	Daily limit reached — enable PAYG or upgrade
500	Internal error — retry with exponential backoff
502	AI provider error — retry once

GitHub Actions Example

Block insecure policies in pull requests with the official AI-Powered Shieldly Action.

name: Shieldly Security Check
on: [pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: AI-Powered IAM Policy Analysis
        uses: shieldly-io/action@v1
        with:
          api-key: ${{ secrets.SHIELDLY_API_KEY }}
          scan-path: ./iam-policy.json
          fail-on-severity: High

curl Quick Start

# Set your API key
export SHIELDLY_API_KEY="sk_live_..."

# Analyze an IAM policy file
curl -X POST https://api.shieldly.io/v1/analyze/iam \
  -H "Authorization: Bearer $SHIELDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"policy\": $(cat my-policy.json | jq -Rs .)}"

# Check usage
curl https://api.shieldly.io/v1/usage \
  -H "Authorization: Bearer $SHIELDLY_API_KEY"

Amazon Web Services (AWS) is a trademark of Amazon.com, Inc. Shieldly is not affiliated with, endorsed by, or sponsored by Amazon Web Services.