Core Concepts

This page explains the core domain objects and concepts that power VeraID. Understanding these building blocks is essential for effective use of the platform, whether you are working through the dashboard or integrating via the API.

---

Identities

An identity in VeraID represents a non-human identity (NHI) — any automated actor that authenticates to systems, accesses resources, or performs actions without direct human interaction.

Every identity has a type that describes its function:

Type	Description	Examples
SERVICE_ACCOUNT	Long-lived accounts used by applications and services	GCP service account, AWS IAM role, Azure managed identity
API_KEY	Static keys used to authenticate API requests	Stripe API key, Twilio auth token, internal service keys
OAUTH_TOKEN	OAuth 2.0 client credentials or refresh tokens	GitHub App token, Slack bot token, Salesforce connected app
CI_CD	Tokens and identities used in build and deployment pipelines	GitHub Actions OIDC, GitLab CI token, Jenkins credentials
AI_AGENT	Autonomous AI agents that make decisions and call tools	LLM-powered agents, copilots, autonomous workflows
IOT_DEVICE	Embedded devices that communicate with cloud services	Sensors, gateways, edge compute nodes
KUBERNETES_POD	Workload identities running in Kubernetes clusters	Pod service accounts, SPIFFE identities

Identity attributes

Every identity record includes:

• Owner — The human user responsible for the identity. VeraID maps human-to-NHI relationships so that when an owner leaves the organization, all their NHIs can be flagged or decommissioned automatically.
• Platform — The cloud provider or service where the identity originates (e.g., aws, gcp, azure, github).
• Risk score — A dynamic score from 0 to 100 reflecting the identity’s current security posture.
• Lifecycle state — The current state of the identity (see Lifecycle States below).
• Tags and metadata — Arbitrary key-value pairs for classification, cost center tracking, or integration metadata.

Cross-platform correlation

VeraID correlates identities across providers. A single logical service may have an AWS IAM role, a GCP service account, and a GitHub Actions token — VeraID links these into a unified identity view so you can assess risk and enforce policy holistically.

---

Credentials

A credential is a secret value that an identity uses to authenticate. VeraID acts as a credential vault — storing, encrypting, rotating, and revoking credentials on your behalf.

Credential format

All credentials managed by VeraID follow a consistent format:

kd_{env}_{random}

Prefix	Environment	Use case
kd_live_	Production	Live API calls against production systems
kd_test_	Test / Staging	Development and testing — isolated from production data
kd_jit_	Just-in-time	Short-lived temporary credentials with automatic expiry

Credential types

Type	Description
API_KEY	Static API key for service-to-service authentication
JWT	JSON Web Token, typically short-lived with claims-based authorization
OAUTH_TOKEN	OAuth 2.0 access or refresh token
CERTIFICATE	X.509 certificate for mTLS or code signing
SSH_KEY	SSH public/private key pair for secure shell access
TEMPORARY	Ephemeral credential issued via JIT access, auto-expires after a defined TTL

Encryption at rest

All credential values are encrypted using envelope encryption with AES-256-GCM. A unique data encryption key (DEK) protects each credential. DEKs are themselves encrypted by a key encryption key (KEK) managed through your cloud provider’s KMS. Plaintext credential values are never stored on disk or logged.

Scopes and usage limits

Credentials can be scoped to specific resources and operations. You can also enforce usage limits — for example, restricting a credential to a maximum of 1,000 API calls per day or limiting it to read-only operations on a specific set of endpoints.

---

Policies

VeraID uses policy-based access control (PBAC) to govern what identities can do. Policies are declarative rules that evaluate in real time to produce an ALLOW or DENY decision.

Policy structure

A policy consists of:

• Name and description — Human-readable label and purpose.
• Effect — Either ALLOW or DENY. Deny rules always take precedence over allow rules.
• Subjects — The identities or identity groups the policy applies to.
• Resources — The resources or resource patterns the policy governs.
• Actions — The operations being controlled (e.g., read, write, delete, invoke).
• Conditions — Optional constraints that must be satisfied for the policy to apply.

Condition types

Conditions add contextual constraints to policies:

Condition	Description	Example
Time window	Restrict access to specific hours or days	Allow CI/CD tokens only during business hours
IP range	Restrict access to specific CIDR blocks	Allow only from corporate VPN range 10.0.0.0/8
Rate limit	Cap the number of requests per time window	Maximum 100 requests per minute
MFA required	Require step-up authentication	Require MFA for production credential access
Resource tag	Match against resource metadata	Allow access only to resources tagged env:staging
Risk score	Evaluate against the identity’s current risk score	Deny access if risk score exceeds 75

Policy evaluation

When an identity makes a request, VeraID evaluates all applicable policies:

1. Collect all policies whose subjects, resources, and actions match the request.
2. Evaluate conditions against the current context (time, IP, risk score, etc.).
3. If any matching policy has effect DENY, the request is denied.
4. If at least one matching policy has effect ALLOW, the request is allowed.
5. If no policies match, the request is denied by default (implicit deny).

Note

VeraID follows a deny-by-default model. Every request must be explicitly allowed by at least one policy. This ensures that new identities and resources are secure by default.

---

Risk scoring

Every identity in VeraID has a risk score — a number from 0 to 100 that reflects its current security posture. Risk scores are dynamic and update continuously as conditions change.

Score ranges

Range	Level	Meaning
0–25	Low	Identity follows best practices, no anomalies detected
26–50	Medium	Minor issues detected — e.g., credential approaching expiry
51–75	High	Significant risks — e.g., overprivileged access, behavioral anomaly
76–100	Critical	Immediate action required — e.g., credential leaked, active compromise

Scoring factors

Risk scores are calculated from multiple weighted signals:

• Credential hygiene — Age of credentials, rotation frequency, whether secrets are stored in plaintext.
• Privilege level — Breadth of access, number of policies granting write or admin permissions.
• Behavioral patterns — Deviations from historical usage (unusual hours, new IP ranges, spike in API calls).
• Policy compliance — Whether the identity conforms to organizational policies or has policy violations.
• Exposure analysis — Whether credentials have appeared in public repositories, logs, or breach databases.
• Owner status — Whether the human owner is still active in the organization.

Score-based automation

You can use risk scores to trigger automated responses:

• Alert when an identity’s risk score exceeds a threshold.
• Suspend identities that cross a critical threshold until reviewed.
• Require approval for high-risk identities to access sensitive resources.
• Escalate to the identity owner or security team for investigation.

---

Lifecycle states

Every identity moves through a defined set of lifecycle states. VeraID tracks state transitions and enforces governance rules at each stage.

DISCOVERED → ACTIVE → SUSPENDED → REVOKED
                ↑          ↓
                └──────────┘
                (Reactivate)

State	Description
DISCOVERED	Identity found during a scan but not yet reviewed or onboarded
ACTIVE	Identity is approved, monitored, and permitted to operate
SUSPENDED	Identity is temporarily disabled — credentials are frozen but not destroyed
REVOKED	Identity is permanently decommissioned — all credentials are destroyed

State transitions

• DISCOVERED → ACTIVE — An administrator reviews and approves the identity, assigns an owner, and attaches policies.
• ACTIVE → SUSPENDED — Triggered manually, by a risk score threshold, or by an automated policy (e.g., owner offboarded).
• SUSPENDED → ACTIVE — An administrator reactivates the identity after investigation or remediation.
• ACTIVE → REVOKED or SUSPENDED → REVOKED — Permanent decommissioning. All associated credentials are destroyed and audit records are sealed.

Caution

Revoking an identity is irreversible. All credentials are cryptographically destroyed and cannot be recovered. Ensure dependent services have been migrated before revoking an identity.

---

Organizations and multi-tenancy

VeraID is a multi-tenant platform. Every object — identities, credentials, policies, audit logs — belongs to exactly one organization.

Row-level security (RLS)

Tenant isolation is enforced at the database level using PostgreSQL row-level security. Every table includes an organizationId column, and RLS policies ensure that queries can only return rows belonging to the authenticated user’s organization. This guarantee holds even in the event of application-level bugs — the database itself prevents cross-tenant data access.

Organization hierarchy

Organizations can contain:

• Members — Human users with roles (Owner, Admin, Member, Viewer).
• Identities — All NHIs belonging to the organization.
• Policies — Access control rules scoped to the organization.
• Integrations — Connected cloud providers and SaaS platforms.
• Audit logs — Immutable event records for all organization activity.

---

Audit logging

Every action in VeraID produces an audit log entry — an immutable record of who did what, when, and from where. Audit logs are the foundation of compliance reporting and incident investigation.

Log structure

Each audit log entry contains:

Field	Description
id	Unique event identifier
timestamp	ISO 8601 timestamp with microsecond precision
actor	The identity or user that performed the action
action	The operation performed (e.g., credential.created, policy.updated)
resource	The object that was acted upon
outcome	SUCCESS or FAILURE
metadata	Additional context — IP address, user agent, request ID, risk score at time of action
organizationId	The organization the event belongs to

Immutability and retention

Audit logs are stored in TimescaleDB hypertables — time-series optimized tables that automatically partition data by time. Logs are append-only and cannot be modified or deleted through the application. Retention policies are configurable per organization, with a default retention of 7 years to meet SOC 2 and ISO 27001 requirements.

Tip

Use the audit log API to export events to your SIEM (Splunk, Datadog, Elastic) for centralized monitoring. VeraID supports both pull-based export and push-based webhooks.