Quickstart

This guide walks you through installing the VeraID SDK, connecting to your organization, and performing common operations — all in under five minutes.

Prerequisites

Before you begin, make sure you have the following:

• A VeraID account with an active organization. Sign up at app.veraid.io if you do not have one.
• Node.js 18+ or Python 3.8+ installed on your machine.
• An organization API key with at least read scope. Generate one from Settings → API Keys in the VeraID dashboard.

Tip

Use a kd_test_* key during development. Test keys have the same API surface as production keys but are isolated to your test environment and do not affect production data.

---

Step 1: Install the SDK

Choose your language and install the VeraID SDK:

Node.js / TypeScript

npm install @veraid/sdk

Python

pip install veraid

---

Step 2: Initialize the client

Create a VeraID client instance using your API key and agent ID. The agent ID identifies which non-human identity is making requests — this is required for audit logging and policy evaluation.

TypeScript

import { VeraIDClient } from '@veraid/sdk';

const client = new VeraIDClient({
  apiKey: process.env.VERAID_API_KEY,    // kd_test_abc123... or kd_live_abc123...
  agentId: process.env.VERAID_AGENT_ID,  // Your NHI identity ID
  baseUrl: 'https://app.veraid.io/api/v1', // Optional: defaults to production
});

Python

import os
from veraid import VeraIDClient

client = VeraIDClient(
    api_key=os.environ["VERAID_API_KEY"],
    agent_id=os.environ["VERAID_AGENT_ID"],
    base_url="https://app.veraid.io/api/v1",  # Optional: defaults to production
)

Caution

Never hard-code API keys in your source code. Always load them from environment variables or a secrets manager. VeraID keys begin with kd_ and are flagged by most secret scanning tools.

---

Step 3: Make your first API calls

Retrieve a credential from the vault

Fetch a credential by its ID to use in downstream service calls. Credentials are decrypted server-side and returned only to authorized identities.

TypeScript

// Retrieve a credential from the VeraID vault
const credential = await client.credentials.get('cred_a1b2c3d4');

console.log('Credential type:', credential.type);       // e.g., "API_KEY"
console.log('Expires at:', credential.expiresAt);        // ISO 8601 timestamp
console.log('Scopes:', credential.scopes);               // e.g., ["read", "write"]

// Use the credential value in a downstream call
const response = await fetch('https://api.example.com/data', {
  headers: {
    Authorization: `Bearer ${credential.value}`,
  },
});

Python

# Retrieve a credential from the VeraID vault
credential = client.credentials.get("cred_a1b2c3d4")

print(f"Credential type: {credential.type}")       # e.g., "API_KEY"
print(f"Expires at: {credential.expires_at}")       # ISO 8601 timestamp
print(f"Scopes: {credential.scopes}")               # e.g., ["read", "write"]

# Use the credential value in a downstream call
import requests
response = requests.get(
    "https://api.example.com/data",
    headers={"Authorization": f"Bearer {credential.value}"},
)

Check budget before LLM calls

For AI agent identities, VeraID enforces spend budgets. Always check available budget before making LLM API calls to avoid unexpected denials.

TypeScript

// Check remaining budget for this AI agent
const budget = await client.agents.getBudget();

console.log('Daily limit:', budget.dailyLimit);           // e.g., 50.00 (USD)
console.log('Spent today:', budget.spentToday);            // e.g., 12.34
console.log('Remaining:', budget.remaining);               // e.g., 37.66

if (budget.remaining < 1.0) {
  console.warn('Budget nearly exhausted — deferring LLM call');
  // Gracefully degrade or queue for later
} else {
  // Record the spend and proceed
  const result = await client.agents.recordSpend({
    amount: 0.03,
    model: 'gpt-4o',
    operation: 'chat-completion',
  });

  // Now make your LLM call
  // ...
}

Python

# Check remaining budget for this AI agent
budget = client.agents.get_budget()

print(f"Daily limit: {budget.daily_limit}")            # e.g., 50.00 (USD)
print(f"Spent today: {budget.spent_today}")             # e.g., 12.34
print(f"Remaining: {budget.remaining}")                 # e.g., 37.66

if budget.remaining < 1.0:
    print("Budget nearly exhausted — deferring LLM call")
    # Gracefully degrade or queue for later
else:
    # Record the spend and proceed
    result = client.agents.record_spend(
        amount=0.03,
        model="gpt-4o",
        operation="chat-completion",
    )

    # Now make your LLM call
    # ...

---

Environment variables

Configure the SDK using these environment variables. All are optional except VERAID_API_KEY.

Variable	Required	Default	Description
VERAID_API_KEY	Yes	—	Your organization API key (kd_live_* or kd_test_*)
VERAID_AGENT_ID	Yes	—	The identity ID of the calling NHI or AI agent
VERAID_BASE_URL	No	https://app.veraid.io/api/v1	API base URL. Override for self-hosted or staging environments
VERAID_DEBUG	No	false	Set to true to enable verbose request/response logging

Note

When VERAID_DEBUG is enabled, request and response bodies are logged to stderr. Never enable debug mode in production — it may expose sensitive credential values in your logs.

---

Next steps

Now that you have the SDK installed and a working client, explore these areas:

Core Concepts

Learn about identities, credentials, policies, and risk scoring. Read Core Concepts →

Authentication

Understand API key auth, session cookies, rate limiting, and error handling. Authentication Guide →

Identity Management

Create, update, and manage non-human identities programmatically. Manage Identities →

AI Agent Security

Set up budget controls, tool-call governance, and prompt injection detection. Secure AI Agents →