Managing Identities

VeraID exposes a full set of RESTful endpoints for identity lifecycle management. All endpoints require authentication via a valid API credential and are scoped by your organization’s tenant.

Note

All request and response bodies use JSON. Include Content-Type: application/json and Authorization: Bearer kd_live_... headers with every request.

Create an Identity

Create a new non-human identity in your organization.

Endpoint: POST /api/v1/identities

Request Body

Field	Type	Required	Description
name	string	Yes	Human-readable name (must be unique within your tenant)
type	enum	Yes	NHI type: SERVICE_ACCOUNT, API_KEY, OAUTH_TOKEN, CI_CD, AI_AGENT, IOT_DEVICE, KUBERNETES_POD
description	string	No	Purpose or context for this identity
metadata	object	No	Arbitrary key-value pairs (e.g., team, cost center, environment)
tags	string[]	No	Labels for filtering and policy assignment
allowedIPs	string[]	No	IP allowlist in CIDR notation
allowedOrigins	string[]	No	Permitted HTTP origins
expiresAt	datetime	No	Optional expiration timestamp (ISO 8601)
agentConfig	object	No	AI agent configuration (only for AI_AGENT type)

Example

curl -X POST https://app.veraid.io/api/v1/identities \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deploy-pipeline-staging",
    "type": "CI_CD",
    "description": "GitHub Actions deployment pipeline for the staging environment",
    "metadata": {
      "team": "platform",
      "repository": "acme/web-app",
      "environment": "staging"
    },
    "tags": ["staging", "github-actions", "platform-team"]
  }'

Response

{
  "id": "idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d",
  "name": "deploy-pipeline-staging",
  "type": "CI_CD",
  "status": "ACTIVE",
  "description": "GitHub Actions deployment pipeline for the staging environment",
  "metadata": {
    "team": "platform",
    "repository": "acme/web-app",
    "environment": "staging"
  },
  "tags": ["staging", "github-actions", "platform-team"],
  "allowedIPs": [],
  "allowedOrigins": [],
  "riskScore": 0,
  "lastUsedAt": null,
  "expiresAt": null,
  "agentConfig": null,
  "createdAt": "2026-03-19T10:00:00Z",
  "updatedAt": "2026-03-19T10:00:00Z"
}

List Identities

Retrieve a paginated list of identities with optional filters.

Endpoint: GET /api/v1/identities

Query Parameters

Parameter	Type	Default	Description
type	enum	—	Filter by NHI type
status	enum	—	Filter by lifecycle status (ACTIVE, SUSPENDED, REVOKED)
tags	string	—	Comma-separated list of tags (identities matching any tag are returned)
search	string	—	Full-text search across name and description
page	number	1	Page number (1-indexed)
limit	number	20	Results per page (max 100)

Example

# List all active CI/CD identities tagged with "production"
curl -X GET "https://app.veraid.io/api/v1/identities?type=CI_CD&status=ACTIVE&tags=production&page=1&limit=25" \
  -H "Authorization: Bearer kd_live_your_api_key"

Response

{
  "data": [
    {
      "id": "idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d",
      "name": "deploy-pipeline-production",
      "type": "CI_CD",
      "status": "ACTIVE",
      "riskScore": 8,
      "tags": ["production", "github-actions"],
      "lastUsedAt": "2026-03-19T09:45:00Z",
      "createdAt": "2025-10-15T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "totalPages": 1
  }
}

Get an Identity

Retrieve the full details of a single identity by its ID.

Endpoint: GET /api/v1/identities/{id}

Example

curl -X GET https://app.veraid.io/api/v1/identities/idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d \
  -H "Authorization: Bearer kd_live_your_api_key"

The response contains the full identity object as described in the Identity Overview.

Update an Identity

Modify a mutable field on an existing identity. Only the fields included in the request body are updated; all other fields remain unchanged.

Endpoint: PUT /api/v1/identities/{id}

Updatable Fields

Field	Notes
name	Must remain unique within your tenant
description	Free-text update
metadata	Replaces the entire metadata object (use merge logic client-side)
tags	Replaces the entire tags array
allowedIPs	Replaces the entire IP allowlist
allowedOrigins	Replaces the entire origins list
expiresAt	Set or clear the expiration
agentConfig	Update AI agent configuration (AI_AGENT type only)

Caution

The type and status fields cannot be changed via the update endpoint. Use the dedicated suspend and activate endpoints to manage lifecycle state.

Example

curl -X PUT https://app.veraid.io/api/v1/identities/idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated: now handles both staging and QA deployments",
    "tags": ["staging", "qa", "github-actions", "platform-team"],
    "allowedIPs": ["10.0.0.0/16"]
  }'

Response

Returns the full updated identity object with updatedAt reflecting the modification timestamp.

Delete an Identity

Permanently delete an identity and all associated data. This action removes the identity record, revokes all linked credentials, and deletes policy bindings.

Endpoint: DELETE /api/v1/identities/{id}

Danger

Deleting an identity is irreversible. Unlike revocation, which preserves the identity record for audit purposes, deletion permanently removes all associated data. Consider revoking the identity instead if you need to retain audit history.

Example

curl -X DELETE https://app.veraid.io/api/v1/identities/idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d \
  -H "Authorization: Bearer kd_live_your_api_key"

Response

{
  "success": true,
  "message": "Identity deleted successfully"
}

Suspend an Identity

Temporarily disable an identity. All active credentials are invalidated, and authentication attempts are rejected until the identity is reactivated.

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

Request Body

Field	Type	Required	Description
reason	string	No	Reason for suspension (recorded in audit log)

Example

curl -X POST https://app.veraid.io/api/v1/identities/idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d/suspend \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Owner on leave — suspending per offboarding policy"
  }'

Response

{
  "id": "idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d",
  "status": "SUSPENDED",
  "suspendedAt": "2026-03-19T10:30:00Z",
  "suspendedReason": "Owner on leave — suspending per offboarding policy"
}

Activate an Identity

Reactivate a previously suspended identity. Credentials that were active before suspension are restored.

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

Note

Only identities in SUSPENDED status can be activated. Attempting to activate a REVOKED identity returns a 409 Conflict error.

Example

curl -X POST https://app.veraid.io/api/v1/identities/idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d/activate \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json"

Response

{
  "id": "idt_3a1f8c29-b7d4-4e2a-9c8f-1d5e7a2b4c6d",
  "status": "ACTIVE",
  "activatedAt": "2026-03-19T14:00:00Z"
}

Error Responses

All identity endpoints return standard error responses:

Status Code	Meaning	Common Causes
400	Bad Request	Invalid field values, missing required fields
401	Unauthorized	Missing or invalid API credential
403	Forbidden	Insufficient permissions for this operation
404	Not Found	Identity ID does not exist in your tenant
409	Conflict	Name collision, invalid state transition (e.g., activating a revoked identity)
429	Too Many Requests	Rate limit exceeded

{
  "error": {
    "code": "IDENTITY_NOT_FOUND",
    "message": "No identity found with ID idt_invalid_id",
    "status": 404
  }
}

What’s Next

• Risk Scoring — Understand how behavioral signals drive dynamic risk scores
• Identity Groups — Organize identities and apply policies in bulk
• Credential Overview — Issue and manage credentials for your identities