Credential Rotation

Credential rotation is a foundational security practice that limits the window of exposure for compromised secrets. VeraID automates the entire rotation lifecycle — from scheduling and notification to grace-period overlap and downstream sync — so your team can enforce rotation policies without manual intervention or service disruptions.

Rotation Policy Configuration

Every credential can have a rotation policy that defines how and when it should be rotated. The policy is set at credential creation time or updated later.

Field	Type	Required	Description
intervalDays	number	Yes	Number of days between automatic rotations
gracePeriodHours	number	Yes	Hours during which both old and new credentials are valid
notifyDaysBefore	number	No	Days before rotation to send advance notifications
notifyChannels	string[]	No	Notification channels: in_app, email, webhook

Example Rotation Policy

{
  "rotationPolicy": {
    "intervalDays": 90,
    "gracePeriodHours": 24,
    "notifyDaysBefore": 7,
    "notifyChannels": ["in_app", "email", "webhook"]
  }
}

This policy rotates the credential every 90 days, sends notifications 7 days in advance through all three channels, and keeps the old credential valid for 24 hours after the new one is issued.

How Rotation Works

The rotation process follows a carefully sequenced flow designed for zero downtime.

Day 83           Day 90                    Day 91
  │                 │                         │
  ▼                 ▼                         ▼
Notify         New credential issued     Old credential revoked
team           Old still valid           Only new credential works
               (grace period starts)     (grace period ends)

Step-by-Step

1. Advance notification — notifyDaysBefore days before the scheduled rotation, VeraID sends notifications through the configured channels. The notification includes the credential ID, identity name, and scheduled rotation date.

2. New credential issued — On the rotation date, VeraID generates a new credential with the same type, scopes, and policies as the original. The new credential is immediately active.

3. Grace period — For the duration of gracePeriodHours, both the old and new credentials are valid. This overlap window allows your services to pick up the new credential without downtime.

4. Old credential revoked — After the grace period expires, the old credential’s status transitions to REVOKED and can no longer be used for authentication.

Tip

Set your grace period long enough for all consumers to pick up the new credential. For credentials synced to external secret stores, 24 hours is a reasonable default. For credentials consumed by a single service with fast deployment cycles, 2–4 hours may suffice.

Rotate a Credential via API

Trigger an immediate rotation for a specific credential.

Endpoint: POST /api/v1/credentials/{id}/rotate

Request Body

Field	Type	Required	Description
gracePeriodHours	number	No	Override the default grace period for this rotation (defaults to the credential’s policy)
reason	string	No	Reason for rotation (recorded in audit log)

Example

curl -X POST https://app.veraid.io/api/v1/credentials/crd_9f24d67e-a1b3-4c5d-8e7f-2a3b4c5d6e7f/rotate \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriodHours": 4,
    "reason": "Scheduled quarterly rotation"
  }'

Response

{
  "previousCredentialId": "crd_9f24d67e-a1b3-4c5d-8e7f-2a3b4c5d6e7f",
  "newCredential": {
    "id": "crd_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "credential": "kd_live_nE8wC7rD6eN5tI4aL3sK2jH1gF0eD9cB",
    "type": "API_KEY",
    "status": "ACTIVE",
    "prefix": "kd_live_nE8w",
    "lastFour": "9cB"
  },
  "gracePeriodEndsAt": "2026-03-19T14:00:00Z",
  "previousCredentialStatus": "ROTATED"
}

Caution

The new credential value is returned only once in the rotation response. Capture and store it securely before the response is discarded. If you have credential sync configured, the new credential is automatically pushed to your external secret stores.

Rotation Schedules

Rotation schedules let you manage rotation policies across multiple credentials with centralized configuration and monitoring.

List Rotation Schedules

Retrieve all rotation schedules for your organization.

Endpoint: GET /api/v1/rotation-schedules

curl -X GET https://app.veraid.io/api/v1/rotation-schedules \
  -H "Authorization: Bearer kd_live_your_api_key"

Response

{
  "data": [
    {
      "id": "rs_4a5b6c7d-8e9f-0a1b-2c3d-4e5f6a7b8c9d",
      "name": "production-90-day-rotation",
      "intervalDays": 90,
      "gracePeriodHours": 24,
      "notifyDaysBefore": 7,
      "notifyChannels": ["email", "webhook"],
      "credentialCount": 42,
      "nextRotationAt": "2026-04-15T00:00:00Z",
      "lastRotatedAt": "2026-01-15T00:00:00Z",
      "syncTargets": ["aws-secrets-manager", "github-actions"],
      "createdAt": "2025-10-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1
  }
}

Create a Rotation Schedule

Define a reusable rotation schedule that can be assigned to multiple credentials.

Endpoint: POST /api/v1/rotation-schedules

curl -X POST https://app.veraid.io/api/v1/rotation-schedules \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "critical-services-30-day",
    "intervalDays": 30,
    "gracePeriodHours": 12,
    "notifyDaysBefore": 5,
    "notifyChannels": ["in_app", "email", "webhook"],
    "syncTargets": [
      {
        "type": "AWS_SECRETS_MANAGER",
        "config": {
          "region": "us-east-1",
          "secretName": "/prod/api-credentials"
        }
      }
    ]
  }'

Trigger Immediate Rotation for a Schedule

Force all credentials in a rotation schedule to rotate immediately.

Endpoint: POST /api/v1/rotation-schedules/{id}/rotate-now

curl -X POST https://app.veraid.io/api/v1/rotation-schedules/rs_4a5b6c7d-8e9f-0a1b-2c3d-4e5f6a7b8c9d/rotate-now \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Security audit — rotating all production credentials"
  }'

Note

Bulk rotation via schedules is processed asynchronously. The response includes a job ID that you can poll for progress via GET /api/v1/jobs/{jobId}.

Emergency Rotation

Emergency rotation bypasses the normal scheduling cycle and is designed for rapid response to security incidents. Emergency rotations are logged with elevated audit severity and can trigger incident response workflows.

Emergency Rotation Reasons

Reason	Description
COMPROMISED	Credential is confirmed or suspected to be compromised
SUSPICIOUS_ACTIVITY	Anomalous usage patterns detected that warrant immediate rotation
SECURITY_AUDIT	Rotation required as part of a security audit or compliance review
DATA_BREACH	Organizational data breach requiring rotation of all potentially affected credentials

Example: Emergency Rotation

curl -X POST https://app.veraid.io/api/v1/credentials/crd_9f24d67e-a1b3-4c5d-8e7f-2a3b4c5d6e7f/rotate \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriodHours": 0,
    "reason": "COMPROMISED",
    "emergency": true
  }'

Danger

Setting gracePeriodHours to 0 during an emergency rotation immediately revokes the old credential with no overlap period. Any service still using the old credential will lose access instantly. Use this only when the credential is confirmed or strongly suspected to be compromised.

Emergency Rotation for All Credentials

In the event of a data breach or widespread compromise, you can trigger emergency rotation across your entire organization or a specific group:

# Rotate all credentials in a group
curl -X POST https://app.veraid.io/api/v1/groups/grp_a4e7c1d9-3b8f-42e6-9a1c-5d7f2e8b0c3a/rotate-credentials \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "DATA_BREACH",
    "emergency": true,
    "gracePeriodHours": 1
  }'

Rotation Audit Trail

Every rotation event is recorded in the immutable audit log with the following details:

• Previous credential ID and new credential ID
• Rotation trigger (scheduled, manual, emergency)
• Reason (if provided)
• Grace period configuration
• Sync target results (success/failure per target)
• Actor who initiated the rotation (for manual/emergency rotations)

View rotation history via the audit log:

curl -X GET "https://app.veraid.io/api/v1/audit?action=credential.rotated&resourceId=crd_9f24d67e-a1b3-4c5d-8e7f-2a3b4c5d6e7f&limit=10" \
  -H "Authorization: Bearer kd_live_your_api_key"

What’s Next

• Credential Sync — Automatically push rotated credentials to external secret stores
• Credential Verification — Validate credentials at runtime
• Identity Groups — Apply rotation policies to groups of identities