Identity Endpoints

Identities represent non-human entities in your organization such as service accounts, API keys, CI/CD pipelines, and AI agents. Each identity has a type, lifecycle status, risk score, and associated metadata.

List Identities

Retrieve a paginated list of identities with optional filters.

GET /api/v1/identities

Query Parameters

Parameter	Type	Description
type	string	Filter by identity type: SERVICE_ACCOUNT, API_KEY, CI_CD, AI_AGENT
status	string	Filter by status: ACTIVE, SUSPENDED, REVOKED, PENDING
tags	string	Comma-separated list of tags to filter by
search	string	Search by name or description (case-insensitive partial match)
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/identities?type=SERVICE_ACCOUNT&status=ACTIVE&limit=10" \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "data": [
    {
      "id": "id_abc123",
      "name": "aws-deploy-prod",
      "type": "SERVICE_ACCOUNT",
      "status": "ACTIVE",
      "description": "Production deployment service account for AWS",
      "riskScore": 42,
      "tags": ["production", "aws", "deploy"],
      "metadata": {
        "provider": "AWS",
        "region": "us-east-1"
      },
      "owner": {
        "id": "usr_xyz789",
        "name": "Alice Johnson",
        "email": "alice@company.com"
      },
      "credentialCount": 2,
      "lastActivityAt": "2026-03-19T09:15:00Z",
      "createdAt": "2025-06-01T10:00:00Z",
      "updatedAt": "2026-03-18T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 47,
    "totalPages": 5,
    "hasMore": true
  }
}

---

Create Identity

Create a new non-human identity.

POST /api/v1/identities

Request Body

Field	Type	Required	Description
name	string	Yes	Unique name for the identity (2-100 characters)
type	string	Yes	Identity type: SERVICE_ACCOUNT, API_KEY, CI_CD, AI_AGENT
description	string	No	Human-readable description
metadata	object	No	Arbitrary key-value metadata
tags	string[]	No	Tags for filtering and organization
allowedIPs	string[]	No	IP addresses or CIDR ranges allowed to use this identity
allowedOrigins	string[]	No	Allowed HTTP origins for browser-based access
expiresAt	string	No	ISO 8601 expiration date for the identity
agentConfig	object	No	AI agent-specific configuration (required when type is AI_AGENT)

Example Request

curl -X POST https://app.veraid.io/api/v1/identities \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "analytics-pipeline-prod",
    "type": "SERVICE_ACCOUNT",
    "description": "Production analytics data pipeline",
    "metadata": {
      "provider": "GCP",
      "project": "analytics-prod",
      "team": "data-engineering"
    },
    "tags": ["production", "gcp", "analytics", "data-pipeline"],
    "allowedIPs": ["10.0.0.0/8", "172.16.0.0/12"],
    "expiresAt": "2027-03-19T00:00:00Z"
  }'

Example Response

{
  "id": "id_def456",
  "name": "analytics-pipeline-prod",
  "type": "SERVICE_ACCOUNT",
  "status": "ACTIVE",
  "description": "Production analytics data pipeline",
  "riskScore": 0,
  "tags": ["production", "gcp", "analytics", "data-pipeline"],
  "metadata": {
    "provider": "GCP",
    "project": "analytics-prod",
    "team": "data-engineering"
  },
  "allowedIPs": ["10.0.0.0/8", "172.16.0.0/12"],
  "allowedOrigins": [],
  "expiresAt": "2027-03-19T00:00:00Z",
  "owner": null,
  "credentialCount": 0,
  "lastActivityAt": null,
  "createdAt": "2026-03-19T10:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

AI Agent Example

curl -X POST https://app.veraid.io/api/v1/identities \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support-agent",
    "type": "AI_AGENT",
    "description": "Customer support AI agent powered by GPT-4",
    "tags": ["ai-agent", "customer-support", "production"],
    "agentConfig": {
      "model": "gpt-4",
      "provider": "openai",
      "budgetLimit": 1000.00,
      "budgetPeriod": "monthly",
      "maxTokensPerRequest": 4096,
      "promptInjectionDetection": true,
      "mcpServers": ["crm-server", "knowledge-base"]
    }
  }'

---

Get Identity

Retrieve a single identity by ID.

GET /api/v1/identities/{id}

Example Request

curl -X GET https://app.veraid.io/api/v1/identities/id_abc123 \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "id": "id_abc123",
  "name": "aws-deploy-prod",
  "type": "SERVICE_ACCOUNT",
  "status": "ACTIVE",
  "description": "Production deployment service account for AWS",
  "riskScore": 42,
  "tags": ["production", "aws", "deploy"],
  "metadata": {
    "provider": "AWS",
    "region": "us-east-1"
  },
  "allowedIPs": ["10.0.0.0/8"],
  "allowedOrigins": [],
  "expiresAt": null,
  "owner": {
    "id": "usr_xyz789",
    "name": "Alice Johnson",
    "email": "alice@company.com"
  },
  "credentialCount": 2,
  "credentials": [
    {
      "id": "cred_aaa111",
      "name": "Primary Access Key",
      "status": "ACTIVE",
      "lastUsedAt": "2026-03-19T09:15:00Z",
      "expiresAt": "2026-06-01T00:00:00Z"
    },
    {
      "id": "cred_bbb222",
      "name": "Backup Access Key",
      "status": "ACTIVE",
      "lastUsedAt": "2026-02-10T14:00:00Z",
      "expiresAt": "2026-06-01T00:00:00Z"
    }
  ],
  "lastActivityAt": "2026-03-19T09:15:00Z",
  "createdAt": "2025-06-01T10:00:00Z",
  "updatedAt": "2026-03-18T14:30:00Z"
}

---

Update Identity

Update an existing identity. Only the fields provided in the request body are updated.

PUT /api/v1/identities/{id}

Example Request

curl -X PUT https://app.veraid.io/api/v1/identities/id_abc123 \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Production deployment service account for AWS (us-east-1 and us-west-2)",
    "tags": ["production", "aws", "deploy", "multi-region"],
    "allowedIPs": ["10.0.0.0/8", "172.16.0.0/12"],
    "metadata": {
      "provider": "AWS",
      "regions": ["us-east-1", "us-west-2"]
    }
  }'

Example Response

{
  "id": "id_abc123",
  "name": "aws-deploy-prod",
  "type": "SERVICE_ACCOUNT",
  "status": "ACTIVE",
  "description": "Production deployment service account for AWS (us-east-1 and us-west-2)",
  "riskScore": 42,
  "tags": ["production", "aws", "deploy", "multi-region"],
  "metadata": {
    "provider": "AWS",
    "regions": ["us-east-1", "us-west-2"]
  },
  "allowedIPs": ["10.0.0.0/8", "172.16.0.0/12"],
  "allowedOrigins": [],
  "expiresAt": null,
  "owner": {
    "id": "usr_xyz789",
    "name": "Alice Johnson",
    "email": "alice@company.com"
  },
  "credentialCount": 2,
  "lastActivityAt": "2026-03-19T09:15:00Z",
  "createdAt": "2025-06-01T10:00:00Z",
  "updatedAt": "2026-03-19T10:05:00Z"
}

---

Delete Identity

Permanently delete an identity and all associated credentials. This action cannot be undone.

DELETE /api/v1/identities/{id}

Example Request

curl -X DELETE https://app.veraid.io/api/v1/identities/id_abc123 \
  -H "Authorization: Bearer kd_live_abc123..."

Example Response

{
  "message": "Identity deleted successfully",
  "id": "id_abc123",
  "credentialsRevoked": 2
}

Danger

Deleting an identity immediately revokes all associated credentials. Any services using those credentials will lose access. Consider suspending the identity first to validate impact before permanent deletion.

---

Suspend Identity

Temporarily suspend an identity, disabling all its credentials without revoking them.

POST /api/v1/identities/{id}/suspend

Example Request

curl -X POST https://app.veraid.io/api/v1/identities/id_abc123/suspend \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Suspicious activity detected - investigating anomalous access pattern"
  }'

Example Response

{
  "id": "id_abc123",
  "name": "aws-deploy-prod",
  "status": "SUSPENDED",
  "suspendedAt": "2026-03-19T10:10:00Z",
  "suspendedBy": "usr_admin001",
  "suspendReason": "Suspicious activity detected - investigating anomalous access pattern",
  "credentialsSuspended": 2
}

Note

Suspending an identity is reversible. All credentials are preserved and can be reactivated when the identity is activated again.

---

Activate Identity

Reactivate a suspended identity, re-enabling all its credentials.

POST /api/v1/identities/{id}/activate

Example Request

curl -X POST https://app.veraid.io/api/v1/identities/id_abc123/activate \
  -H "Authorization: Bearer kd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Investigation complete - no malicious activity confirmed"
  }'

Example Response

{
  "id": "id_abc123",
  "name": "aws-deploy-prod",
  "status": "ACTIVE",
  "activatedAt": "2026-03-19T11:00:00Z",
  "activatedBy": "usr_admin001",
  "activateReason": "Investigation complete - no malicious activity confirmed",
  "credentialsReactivated": 2
}