Credential Rotation

Overview

As an insurance platform, Tawa enforces security compliance automatically. Every service with database credentials gets a 30-day rotation cycle. When the cycle expires, credentials are regenerated and the service is redeployed with fresh credentials — no action required from developers.

How it works

1. When you deploy a service, the builder stamps a rotation clock on it: lastRotatedAt (now) and nextRotationAt (now + 30 days)
2. The rotation scheduler checks all services every hour for approaching expirations
3. At 7 days out: you receive a warning email
4. At 3 days out: you receive an imminent-rotation email
5. At 0 days (expiration): the platform triggers an automatic redeploy with fresh credentials
6. After rotation: you receive a confirmation email and the clock resets to 30 days

Rotation clock

Every deploy resets the rotation clock. This means if you deploy regularly (e.g., weekly), you'll never hit the automatic rotation — each deploy starts a fresh 30-day window.

The clock tracks:

Trigger types

Email notifications

The platform sends email notifications at key points in the rotation cycle. Emails are sent once per cycle (deduplication prevents repeated emails for the same rotation window).

Emails are sent to the service creator's email address. If no email is on file, they fall back to admin@<org>.io.

Zero-downtime rotation

All rotations (automatic and manual) use Kubernetes rolling updates to ensure zero downtime:

1. A new pod is started with fresh credentials (maxSurge: 1)
2. The new pod passes health checks and begins serving traffic
3. The old pod is terminated (maxUnavailable: 0)

This means your service has two pods running for approximately 2-3 minutes during the rotation. There is no downtime and no dropped requests.

Manual refresh

You can manually refresh credentials at any time, which resets the 30-day clock:

Via the console

Navigate to your service in the console. Scroll to the Credential Rotation section and click Refresh Now. This triggers a redeploy at the current commit with fresh credentials.

Via the API

# Manual credential refresh
POST /services/:name/rotation/refresh

# Optional: target a specific environment
{
  "environment": "prod"  // or "sandbox", "uat", "dev"
}

The API returns a 202 Accepted with a buildId you can use to track the redeploy.

Viewing rotation status

# Get rotation status for a service
GET /services/:name/rotation

# Response:
{
  "rotation": {
    "lastRotatedAt": "2026-02-17T12:00:00Z",
    "nextRotationAt": "2026-03-19T12:00:00Z",
    "rotationPolicy": "auto",
    "rotationHistory": [
      {
        "rotatedAt": "2026-02-17T12:00:00Z",
        "trigger": "deploy",
        "environment": "prod",
        "buildId": "abc12345-..."
      }
    ]
  }
}

Compliance dashboard

The Compliance page in the console shows all services approaching rotation:

• Compliant (green) — more than 7 days remaining
• Expiring (yellow) — 3 to 7 days remaining
• Critical / Overdue (red) — 3 days or fewer, or past due

Each service shows a progress bar indicating how far through the 30-day cycle it is. Super admins see all services across all orgs; regular users see only their own org's services.

Compliance fee

Each automatic credential rotation incurs a flat compliance fee of 1,500 gas tokens ($15 USD) per service. This fee is charged to the org's wallet when the auto-rotation triggers.

FAQ

Do I need to change my code?

No. Credential rotation is entirely platform-managed. Your app reads process.env.MONGODB_URI (or REDIS_URL, NEO4J_URI) on startup. When credentials rotate, your pod restarts with new env vars automatically.

What if I deploy every week?

Each deploy resets the 30-day clock. If you deploy at least once every 30 days, automatic rotation will never trigger and you'll never be charged the compliance fee.

What if the auto-rotation build fails?

The scheduler has a safety check: if the last 3 builds for a service all failed, it skips auto-rotation and logs a warning. This prevents a broken service from getting stuck in a rotation loop. Fix the underlying issue and deploy manually to resume the cycle.

Can I disable automatic rotation?

Rotation policy can be set to manual instead of auto, which disables the scheduler for that service. However, this is not recommended — manual-policy services still show the rotation clock, but the platform won't auto-redeploy when it expires. You are responsible for rotating credentials yourself.

Does rotation affect my data?

No. Rotation only changes the credentials used to connect to your database. The data itself is untouched. The old credentials are invalidated and new ones are generated.

How does zero-downtime work with a single replica?

Even with one replica, Kubernetes temporarily runs two pods during rolling updates (maxSurge: 1). The new pod starts, passes its health check, and begins receiving traffic before the old pod is terminated. The extra pod only exists for 2-3 minutes.

Is there an API to check rotation status?

Yes. GET /services/:name/rotation returns the full rotation state. GET /rotation/upcoming returns all services approaching rotation within 14 days (org-scoped).

Related

• Databases — how database provisioning works
• Gas & Wallets — token economics and the compliance fee
• Config & Secrets — managing secrets and environment variables