API Overview

The VeraID API provides programmatic access to all identity governance capabilities, including identity management, credential lifecycle, policy enforcement, audit logging, and integrations.

Base URL

https://app.veraid.io/api/v1

All API endpoints are prefixed with /api/v1. The API is served over HTTPS only. HTTP requests are rejected.

Authentication

The VeraID API supports two authentication methods:

API Key (Bearer Token)

Include your API key in the Authorization header using the Bearer scheme:

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

API keys follow the format kd_{env}_{random}:

Prefix	Environment	Description
kd_live_	Production	Full access to production data
kd_test_	Test	Access to test/sandbox data only

Caution

API keys are shown only once at creation time. Store them securely using a secrets manager. If you lose an API key, rotate it immediately via the dashboard or API.

Session Cookie

Browser-based requests from the VeraID dashboard use session cookies managed by NextAuth. This method is used automatically when interacting with the API through the web interface and is not intended for programmatic access.

---

Content Type

All requests and responses use JSON. Include the Content-Type header for requests with a body:

Content-Type: application/json

---

Rate Limiting

API requests are rate-limited to ensure fair usage and platform stability.

Limit	Value
Requests per minute	100
Burst allowance	20 (above the per-minute rate)

Rate limit status is communicated via response headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per minute
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the rate limit window resets

When the rate limit is exceeded, the API responds with a 429 Too Many Requests status:

{
  "error": "Rate limit exceeded",
  "details": {
    "limit": 100,
    "remaining": 0,
    "resetAt": "2026-03-19T10:01:00Z"
  }
}

Tip

Implement exponential backoff with jitter when retrying rate-limited requests. Start with a 1-second delay and increase exponentially up to 30 seconds.

---

Organization Scoping

All API requests are automatically scoped to the organization associated with the API key. You cannot access resources belonging to other organizations. The organization context is derived from the API key and does not need to be specified in the request.

---

Error Format

All error responses follow a consistent structure:

{
  "error": "Human-readable error message",
  "details": {
    "field": "Additional context about the error"
  }
}

The details object provides additional context and varies by error type. For validation errors, it contains field-level error messages:

{
  "error": "Validation failed",
  "details": {
    "name": "Name is required",
    "type": "Must be one of: SERVICE_ACCOUNT, API_KEY, CI_CD, AI_AGENT"
  }
}

---

Status Codes

Code	Meaning	Description
200	OK	Request succeeded. Response body contains the requested data.
201	Created	Resource created successfully. Response body contains the new resource.
400	Bad Request	Invalid request body, missing required fields, or validation failure.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Valid API key but insufficient permissions for the requested operation.
404	Not Found	The requested resource does not exist or is not accessible within your organization.
429	Too Many Requests	Rate limit exceeded. Retry after the time indicated in the X-RateLimit-Reset header.
500	Internal Server Error	An unexpected error occurred. Contact support if the issue persists.

---

Pagination

List endpoints support cursor-based pagination using page and limit query parameters:

curl -X GET "https://app.veraid.io/api/v1/identities?page=2&limit=25" \
  -H "Authorization: Bearer kd_live_abc123..."

Response:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 25,
    "total": 142,
    "totalPages": 6,
    "hasMore": true
  }
}

Parameter	Default	Maximum	Description
page	1	—	Page number (1-indexed)
limit	20	100	Number of items per page

---

Request ID

Every API response includes an X-Request-Id header containing a unique identifier for the request. Include this ID when contacting support to help diagnose issues:

X-Request-Id: req_abc123def456

---

SDK Support

Official SDKs are available for TypeScript and Python, providing type-safe wrappers around the API with built-in retry logic, rate limit handling, and error typing.

• TypeScript SDK
• Python SDK