Discovery Endpoints

Discovery scans your connected cloud providers to find unmanaged non-human identities (NHIs) that are not yet tracked in VeraID. This helps you identify shadow service accounts, orphaned API keys, and other credentials that may pose a security risk.

How Discovery Works

1. Scan — VeraID queries your connected cloud providers (AWS, GCP, Azure, Kubernetes) for all NHIs.
2. Compare — Discovered NHIs are compared against your existing VeraID inventory to identify unmanaged entities.
3. Assess — Each unmanaged NHI is assessed for risk indicators such as stale credentials, excessive permissions, and missing owners.
4. Import — Review discovered NHIs and selectively import them into VeraID for governance.

---

Start a Discovery Scan

Initiate a discovery scan across one or more connected cloud providers.

POST /api/v1/discovery/scans

Request Body

Field	Type	Required	Description
providers	string[]	No	Providers to scan (default: all connected). Values: AWS, GCP, AZURE, KUBERNETES
filters	object	No	Scope the scan by tags, regions, or projects

Example Request

curl -X POST https://app.veraid.io/api/v1/discovery/scans \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "providers": ["AWS", "GCP"],
    "filters": {
      "regions": ["us-east-1", "us-west-2", "us-central1"],
      "excludeTags": {
        "veraid-ignore": ["true"]
      }
    }
  }'

Example Response

{
  "id": "scan_abc123",
  "status": "IN_PROGRESS",
  "providers": ["AWS", "GCP"],
  "startedAt": "2026-03-19T10:00:00Z",
  "completedAt": null,
  "stats": null
}

---

Get Scan Status

Check the status and results of a discovery scan.

GET /api/v1/discovery/scans/{id}

Example Request

curl -X GET https://app.veraid.io/api/v1/discovery/scans/scan_abc123 \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response (Completed)

{
  "id": "scan_abc123",
  "status": "COMPLETED",
  "providers": ["AWS", "GCP"],
  "startedAt": "2026-03-19T10:00:00Z",
  "completedAt": "2026-03-19T10:03:45Z",
  "stats": {
    "totalDiscovered": 234,
    "alreadyManaged": 189,
    "unmanaged": 45,
    "byProvider": {
      "AWS": {
        "total": 156,
        "unmanaged": 28
      },
      "GCP": {
        "total": 78,
        "unmanaged": 17
      }
    },
    "byRiskLevel": {
      "CRITICAL": 3,
      "HIGH": 8,
      "MEDIUM": 19,
      "LOW": 15
    }
  }
}

---

List Scan Results

Retrieve the detailed results of a completed discovery scan.

GET /api/v1/discovery/scans/{id}/results

Query Parameters

Parameter	Type	Description
status	string	Filter: UNMANAGED, MANAGED, IGNORED
riskLevel	string	Filter: CRITICAL, HIGH, MEDIUM, LOW
provider	string	Filter by provider: AWS, GCP, AZURE, KUBERNETES
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)

Example Request

curl -X GET "https://app.veraid.io/api/v1/discovery/scans/scan_abc123/results?status=UNMANAGED&riskLevel=HIGH" \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "data": [
    {
      "id": "disc_001",
      "provider": "AWS",
      "externalId": "AIDAEXAMPLE123456",
      "name": "legacy-data-export",
      "type": "IAM_USER",
      "status": "UNMANAGED",
      "riskLevel": "HIGH",
      "riskScore": 82,
      "riskIndicators": [
        {
          "factor": "STALE_CREDENTIALS",
          "description": "Access key has not been rotated in 437 days",
          "severity": "HIGH"
        },
        {
          "factor": "NO_OWNER",
          "description": "No owner tag or identifiable creator found",
          "severity": "HIGH"
        },
        {
          "factor": "EXCESSIVE_PERMISSIONS",
          "description": "IAM user has AdministratorAccess policy attached",
          "severity": "CRITICAL"
        },
        {
          "factor": "INACTIVE",
          "description": "No API activity recorded in the last 180 days",
          "severity": "MEDIUM"
        }
      ],
      "details": {
        "arn": "arn:aws:iam::123456789012:user/legacy-data-export",
        "createdAt": "2024-01-15T10:00:00Z",
        "accessKeys": [
          {
            "id": "AKIAEXAMPLE123",
            "status": "Active",
            "createdAt": "2025-01-07T08:00:00Z",
            "lastUsedAt": "2025-09-20T14:30:00Z"
          }
        ],
        "attachedPolicies": [
          "arn:aws:iam::aws:policy/AdministratorAccess"
        ],
        "tags": {}
      },
      "discoveredAt": "2026-03-19T10:02:00Z"
    },
    {
      "id": "disc_002",
      "provider": "GCP",
      "externalId": "sa-abandoned-pipeline@old-project.iam.gserviceaccount.com",
      "name": "sa-abandoned-pipeline",
      "type": "SERVICE_ACCOUNT",
      "status": "UNMANAGED",
      "riskLevel": "HIGH",
      "riskScore": 76,
      "riskIndicators": [
        {
          "factor": "STALE_CREDENTIALS",
          "description": "Service account key has not been rotated in 312 days",
          "severity": "HIGH"
        },
        {
          "factor": "DOMAIN_WIDE_DELEGATION",
          "description": "Service account has domain-wide delegation enabled",
          "severity": "CRITICAL"
        },
        {
          "factor": "NO_OWNER",
          "description": "Project owner left the organization 6 months ago",
          "severity": "MEDIUM"
        }
      ],
      "details": {
        "email": "sa-abandoned-pipeline@old-project.iam.gserviceaccount.com",
        "projectId": "old-project",
        "createdAt": "2024-06-01T12:00:00Z",
        "keys": [
          {
            "id": "key123",
            "createdAt": "2025-05-10T09:00:00Z",
            "expiresAt": null
          }
        ],
        "roles": [
          "roles/editor",
          "roles/iam.serviceAccountTokenCreator"
        ],
        "domainWideDelegation": true
      },
      "discoveredAt": "2026-03-19T10:03:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "totalPages": 1,
    "hasMore": false
  }
}

---

Import Discovered NHIs

Import one or more discovered NHIs into VeraID for ongoing management and governance.

POST /api/v1/discovery/import

Request Body

Field	Type	Required	Description
discoveryIds	string[]	Yes	IDs of discovered NHIs to import
tags	string[]	No	Tags to apply to all imported identities
ownerId	string	No	User ID to assign as owner for all imported identities
autoRotate	boolean	No	Enable automatic credential rotation on import (default: false)

Example Request

curl -X POST https://app.veraid.io/api/v1/discovery/import \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "discoveryIds": ["disc_001", "disc_002"],
    "tags": ["discovered", "needs-review"],
    "ownerId": "usr_security001",
    "autoRotate": false
  }'

Example Response

{
  "imported": [
    {
      "discoveryId": "disc_001",
      "identityId": "id_imported001",
      "name": "legacy-data-export",
      "type": "SERVICE_ACCOUNT",
      "status": "ACTIVE",
      "riskScore": 82,
      "recommendations": [
        "Rotate access key immediately (437 days old)",
        "Replace AdministratorAccess with least-privilege policy",
        "Assign an owner for governance tracking"
      ]
    },
    {
      "discoveryId": "disc_002",
      "identityId": "id_imported002",
      "name": "sa-abandoned-pipeline",
      "type": "SERVICE_ACCOUNT",
      "status": "ACTIVE",
      "riskScore": 76,
      "recommendations": [
        "Rotate service account key immediately (312 days old)",
        "Review and restrict domain-wide delegation scopes",
        "Verify if this service account is still needed"
      ]
    }
  ],
  "failed": [],
  "summary": {
    "totalRequested": 2,
    "totalImported": 2,
    "totalFailed": 0
  }
}

Tip

After importing discovered NHIs, review the recommendations provided for each identity. Address high-severity risk indicators first, such as stale credentials and excessive permissions, before adding the identity to your regular governance workflow.

---

Ignore Discovered NHIs

Mark discovered NHIs as ignored so they do not appear in future scan results.

POST /api/v1/discovery/ignore

Request Body

Field	Type	Required	Description
discoveryIds	string[]	Yes	IDs of discovered NHIs to ignore
reason	string	No	Reason for ignoring (for audit purposes)

Example Request

curl -X POST https://app.veraid.io/api/v1/discovery/ignore \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "discoveryIds": ["disc_003", "disc_004"],
    "reason": "Third-party managed service accounts - governed by vendor SLA"
  }'

Example Response

{
  "ignored": ["disc_003", "disc_004"],
  "message": "2 discoveries marked as ignored"
}

Caution

Ignored NHIs are excluded from future scan results and risk reporting. Periodically review your ignored list under Settings > Discovery > Ignored to ensure nothing is being overlooked.

---

Scheduling Scans

Configure recurring discovery scans to continuously identify new unmanaged NHIs as they are created across your cloud infrastructure.

POST /api/v1/discovery/schedules

Example Request

curl -X POST https://app.veraid.io/api/v1/discovery/schedules \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Full Scan",
    "schedule": "0 2 * * 1",
    "providers": ["AWS", "GCP", "AZURE"],
    "notifyOnNewFindings": true,
    "notifyChannel": "#security-ops"
  }'

The schedule field uses cron syntax. The example above runs every Monday at 2:00 AM UTC.

Note

Discovery scans are read-only operations. They query your cloud provider APIs to enumerate NHIs but never modify, create, or delete any resources in your cloud accounts.