# SecretCarousel API Reference (llms.txt)
# The agent-native secret vault. AES-256-GCM encryption. Usage-based pricing.
# https://secretcarousel.com

## Authentication
Every request requires: X-API-Key header
Format: sc_free_<tenantId>_<hex> or sc_<tenantId>_<hex>

## Agent Self-Signup
POST /api/signup {"tenantId":"my-project","email":"human@co.dev"}
Returns: {apiKey, tenantId, plan, limits, quickstart}
No password. No verification. Instant API key.

## Secrets (AES-256-GCM encrypted at rest)
POST   /api/v1/secrets              Create: {name, value, secretType, tags[], projectId}
GET    /api/v1/secrets              List (metadata only, no values). Filter: ?secretType=&category=&environment=
GET    /api/v1/secrets/:id          Get with decrypted value. Access logged.
PUT    /api/v1/secrets/:id          Update (creates new version). {value, description, tags[]}
DELETE /api/v1/secrets/:id          Delete. Audit logged.
GET    /api/v1/secrets/:id/versions Version history.

secretType: database-credentials | api-key | certificate | oauth-token | encryption-key | configuration | custom

## Secret Sharing (Pro plan)
POST   /api/v1/shares              Create share: {secretId, expirationHours, maxUses, password?, allowedIPs[]}
POST   /api/v1/shares/access/:token Access shared secret (public, no auth needed). {password?}
GET    /api/v1/shares              List active shares.
DELETE /api/v1/shares/:id          Revoke share.

## Secret Rotation (Pro plan)
GET    /api/v1/rotation            List rotation policies.
POST   /api/v1/rotation            Create: {secretId, schedule (cron), alertDaysBefore, alertEmail}
PUT    /api/v1/rotation/:id        Update policy.
DELETE /api/v1/rotation/:id        Remove policy.
POST   /api/v1/rotation/:id/rotate-now   Rotate immediately.

## Claim Tokens (Pro plan - cross-agent key exchange via Buggazi contracts)
POST   /api/v1/claim-tokens        Create: {secretValue, secretName, targetTenantId, contractId, expiresInMinutes?}
POST   /api/v1/claim-tokens/:token/claim  Claim and auto-store in vault. Returns {secretId}.
GET    /api/v1/claim-tokens        List (created by or targeted at your tenant).
DELETE /api/v1/claim-tokens/:id    Revoke claim token.

## Projects
POST   /api/v1/projects            Create: {name, description, tags[]}
GET    /api/v1/projects            List with secret counts.
GET    /api/v1/projects/:id        Project details.
PUT    /api/v1/projects/:id        Update.
DELETE /api/v1/projects/:id        Delete (must remove secrets first).

## API Keys
POST   /api/v1/api-keys            Create: {name, permissions, projectScope[], expiresAt}
GET    /api/v1/api-keys            List (never shows full key).
PUT    /api/v1/api-keys/:id        Update permissions/scope.
DELETE /api/v1/api-keys/:id        Revoke.
POST   /api/v1/api-keys/:id/regenerate  New key, old invalidated.

permissions: read | write | admin

## Audit Trail
GET    /api/v1/audit               Query: ?action=&resourceType=&startDate=&endDate=&limit=&offset=
GET    /api/v1/audit/export        Export: ?format=csv|json

## Backup & Recovery
POST   /api/v1/backup              Create encrypted backup.
GET    /api/v1/backup              List backups.
POST   /api/v1/backup/:id/restore  Restore from backup.
DELETE /api/v1/backup/:id          Delete backup.

## Webhooks
POST   /api/v1/webhooks            Create: {url, events[], secret}
GET    /api/v1/webhooks            List.
PUT    /api/v1/webhooks/:id        Update.
DELETE /api/v1/webhooks/:id        Remove.
POST   /api/v1/webhooks/:id/test   Send test payload.

events: secret.created | secret.updated | secret.deleted | secret.rotated | secret.shared | apikey.created | apikey.revoked | backup.created

## Plan & Usage
GET    /api/v1/plan                Current plan, usage, limits.
GET    /api/v1/plan/usage          Detailed usage breakdown.
GET    /api/signup/limits           Public: plan comparison.
GET    /api/quickstart              Machine-readable getting started.

## Pricing
$1 one-time signup (Free plan) or $9.99 one-time (Pro plan)
Usage: $0.40 per secret per month + $0.05 per 10,000 API calls
Free includes: 5 secrets + 10K API calls forever
Pro includes: 50 secrets + 100K API calls, rotation, sharing, claim tokens, webhooks

## SDKs
npm install secretcarousel          CLI (npx secretcarousel signup --tenant my-project)
npm install secretcarousel-sdk      Node.js
pip install secretcarousel           Python
go get github.com/jyswee/secretcarousel-go  Go
gem install secretcarousel           Ruby
cargo add secretcarousel             Rust
composer require secretcarousel/sdk  PHP
dotnet add package SecretCarousel    C#
dart pub add secretcarousel          Dart

## Key Patterns
- Secret IDs: secret-uuid (auto-generated)
- API Key prefix: sc_free_ (free) or sc_ (paid)
- Encryption: AES-256-GCM, PBKDF2 100K iterations, unique salt+IV per secret
- Versioning: auto-version on every PUT
- Audit: every operation logged (immutable)
- Claim tokens: ctk_ prefix, single-use, 5min default TTL

## Documentation
Quickstart: https://secretcarousel.com/docs/quickstart.html
Claude Code: https://secretcarousel.com/docs/quickstart/claude-code.html
API Reference: https://secretcarousel.com/api
npm: https://www.npmjs.com/package/secretcarousel