Secrets API¶

Create, Read, Update, Delete, Rotate, and Share Secrets

Document Version: 1.2.0
Last Updated: 2026-08-23

Endpoints Overview¶

Method	Endpoint	Description
POST	`/api/v1/secrets`	Create a new secret
GET	`/api/v1/secrets`	List secrets in project
GET	`/api/v1/secrets/:id`	Get secret by ID
PUT	`/api/v1/secrets/:id`	Update secret
DELETE	`/api/v1/secrets/:id`	Delete secret (soft)
GET	`/api/v1/secrets/:id/versions`	List secret versions
POST	`/api/v1/secrets/:id/rollback`	Rollback to previous version
POST	`/api/v1/secrets/:id/copy`	Copy secret to another project
POST	`/api/v1/secrets/:id/archive`	Archive secret
POST	`/api/v1/secrets/:id/restore`	Restore archived secret
DELETE	`/api/v1/secrets/:id/permanent`	Permanently delete secret
POST	`/api/v1/secrets/:id/rotate`	Trigger secret rotation
GET	`/api/v1/secrets/:id/rotation-config`	Get rotation configuration
PUT	`/api/v1/secrets/:id/rotation-config`	Update rotation configuration
GET	`/api/v1/secrets/:id/sync-status`	Get sync status
POST	`/api/v1/secrets/:id/force-sync`	Force synchronization
POST	`/api/v1/secrets/:id/environments/:env/force-sync`	Force sync per environment
GET	`/api/v1/secrets/:id/links`	List secret↔integration links
POST	`/api/v1/secrets/:id/links`	Create secret link
DELETE	`/api/v1/secrets/:id/links/:linkId`	Delete secret link
GET, POST	`/api/v1/rotation/templates`	List or create rotation templates
GET, PUT, DELETE	`/api/v1/rotation/templates/:id`	Read, update, or delete a rotation template

Create Secret¶

POST /api/v1/secrets HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "database-password",
  "value": "s3cur3P@ssw0rd!",
  "project_id": "550e8400-e29b-41d4-a716-446655440001",
  "environment": "production",
  "ttl_hours": 2160,
  "metadata": {
    "owner": "dba-team",
    "service": "postgres-main"
  },
  "change_reason": "Initial database password provisioning"
}

Request Fields¶

Field	Type	Required	Description
`key`	string	✅	Secret key name (unique within project, 1–255 chars)
`value`	string	✅	Secret value (encrypted at rest, max 64 KB)
`project_id`	string	✅	Target project ID (UUID)
`environment`	string	—	Environment scope (e.g., `production`, `staging`; max 50 chars)
`ttl_hours`	integer	—	Time-to-live in hours (1–8760; secret expires after this period)
`metadata`	object	—	Arbitrary key-value metadata for organization
`change_reason`	string	—	Audit reason for creating this secret (max 1000 chars)

Response `201 Created`¶

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "status": "stored"
}

!!! note "Security"
    The secret `value` is returned only via `GET /secrets/:id` with appropriate permissions. List endpoints do not include secret values.

---

## List Secrets

```http
GET /api/v1/secrets?project_id=550e8400-e29b-41d4-a716-446655440001&page=1&per_page=25 HTTP/1.1
Authorization: Bearer <token>

Query Parameters¶

Parameter	Type	Description
`project_id`	string	Filter by project (required)
`environment`	string	Filter by environment
`search`	string	Search by key name
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 25, max: 100)

Response `200 OK`¶

{
  "data": [
    {
      "id": "sec_xyz789",
      "name": "database-password",
      "type": "password",
      "description": "Production database master password",
      "version": 3,
      "tags": ["production", "database"],
      "rotation": {
        "enabled": true,
        "next_rotation": "2026-05-11T00:00:00Z"
      },
      "created_at": "2026-02-10T14:30:00Z",
      "updated_at": "2026-02-10T16:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

Get Secret¶

GET /api/v1/secrets/sec_xyz789 HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

{
  "id": "sec_xyz789",
  "name": "database-password",
  "value": "s3cur3P@ssw0rd!",
  "type": "password",
  "description": "Production database master password",
  "version": 3,
  "tags": ["production", "database"],
  "project_id": "proj_abc123",
  "rotation": {
    "enabled": true,
    "interval_days": 90,
    "next_rotation": "2026-05-11T00:00:00Z",
    "last_rotated": "2026-02-10T14:30:00Z"
  },
  "created_at": "2026-02-10T14:30:00Z",
  "updated_at": "2026-02-10T16:45:00Z",
  "created_by": "usr_abc123"
}

Audit

Every GET request that retrieves a decrypted secret value is recorded in the audit log.

Update Secret¶

PUT /api/v1/secrets/sec_xyz789 HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "value": "n3wS3cur3P@ss!",
  "description": "Updated production database password"
}

Updatable Fields¶

Field	Description
`value`	New secret value (creates a new version)
`description`	Updated description
`tags`	Updated tags
`rotation.enabled`	Enable/disable rotation
`rotation.interval_days`	Update rotation interval

Response `200 OK`¶

Returns the updated secret metadata (value not included).

Delete Secret¶

DELETE /api/v1/secrets/sec_xyz789 HTTP/1.1
Authorization: Bearer <token>

Response `204 No Content`¶

Soft Delete vs Permanent

DELETE /secrets/:id performs a soft delete. The secret can be restored via POST /secrets/:id/restore. For permanent, irreversible deletion use DELETE /secrets/:id/permanent.

Archive & Restore¶

Archive Secret¶

POST /api/v1/secrets/sec_xyz789/archive HTTP/1.1
Authorization: Bearer <token>

Moves the secret to the archive. Archived secrets are not accessible via normal queries.

Restore Secret¶

POST /api/v1/secrets/sec_xyz789/restore HTTP/1.1
Authorization: Bearer <token>

Restores a previously archived secret back to active state.

Permanent Delete¶

DELETE /api/v1/secrets/sec_xyz789/permanent HTTP/1.1
Authorization: Bearer <token>

Irreversible

Permanent deletion cannot be undone. All versions are removed.

Copy Secret¶

POST /api/v1/secrets/sec_xyz789/copy HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Copies a secret to another project or environment.

Secret Versions¶

List Versions¶

GET /api/v1/secrets/sec_xyz789/versions HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

{
  "data": [
    {
      "version": 3,
      "created_at": "2026-02-10T16:45:00Z",
      "created_by": "usr_abc123",
      "change_type": "manual_update"
    },
    {
      "version": 2,
      "created_at": "2026-01-15T10:00:00Z",
      "created_by": "system",
      "change_type": "rotation"
    },
    {
      "version": 1,
      "created_at": "2026-02-10T14:30:00Z",
      "created_by": "usr_abc123",
      "change_type": "initial"
    }
  ]
}

Rollback Secret¶

POST /api/v1/secrets/sec_xyz789/rollback HTTP/1.1
Authorization: Bearer <token>

Creates a new version with the value from a previous version.

Secret Rotation¶

Get Rotation Config¶

GET /api/v1/secrets/sec_xyz789/rotation-config HTTP/1.1
Authorization: Bearer <token>

Returns the current rotation configuration for the secret.

Update Rotation Config¶

PUT /api/v1/secrets/sec_xyz789/rotation-config HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Updates the rotation configuration (interval, enabled/disabled, provider settings).

Trigger Rotation¶

POST /api/v1/secrets/sec_xyz789/rotate HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

{
  "id": "sec_xyz789",
  "version": 4,
  "rotated_at": "2026-02-10T17:00:00Z",
  "next_rotation": "2026-05-11T17:00:00Z"
}

Synchronization¶

Get Sync Status¶

GET /api/v1/secrets/sec_xyz789/sync-status HTTP/1.1
Authorization: Bearer <token>

Response `200 OK`¶

{
  "id": "sec_xyz789",
  "sync_enabled": true,
  "targets": [
    {
      "target_id": "dc_east",
      "status": "synced",
      "last_synced": "2026-02-10T17:00:00Z",
      "version": 3
    },
    {
      "target_id": "dc_west",
      "status": "pending",
      "last_synced": "2026-02-10T16:45:00Z",
      "version": 2
    }
  ]
}

Force Sync¶

POST /api/v1/secrets/sec_xyz789/force-sync HTTP/1.1
Authorization: Bearer <token>

Force Sync (Per Environment)¶

POST /api/v1/secrets/sec_xyz789/environments/production/force-sync HTTP/1.1
Authorization: Bearer <token>

Forces synchronization for a specific environment only.

Secret Links¶

Secrets can be linked to external integrations (secret managers, cloud providers) for automatic synchronization.

List Links¶

GET /api/v1/secrets/sec_xyz789/links HTTP/1.1
Authorization: Bearer <token>

Create Link¶

POST /api/v1/secrets/sec_xyz789/links HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Links the secret to an external integration target.

Delete Link¶

DELETE /api/v1/secrets/sec_xyz789/links/link_abc123 HTTP/1.1
Authorization: Bearer <token>

Rotation Template Catalog¶

Rotation templates are reusable catalog records scoped to the authenticated organization. The API supports create, list, read, update, and delete operations. A caller cannot use organization_id to access or create a template in another organization. An optional project_id further limits a template to a project in the same organization.

POST /api/v1/rotation/templates HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "standard-90-day",
  "description": "Approved 90-day rotation settings",
  "rotation_interval_days": 90,
  "lead_time_days": 14,
  "grace_period_days": 3,
  "secret_custody_mode": "local"
}

Field	Type	Description
`name`	string	Required catalog name
`project_id`	string	Optional project scope; the project must belong to the authenticated organization
`rotation_interval_days`	integer	Cataloged rotation interval
`lead_time_days`	integer	Cataloged lead time before expiry or due date
`grace_period_days`	integer	Cataloged overlap or rollback grace period
`secret_custody_mode`	string	Cataloged secret custody mode: `local`, `transient`, or `delegated`
`is_default`	boolean	Marks the organization's default catalog entry; only one can be default

Catalog only

Creating or marking a rotation template as default does not automatically apply its values to existing or new rotation configurations. No automatic inheritance or application is performed; configure each rotation resource explicitly.

Required Permissions¶

Operation	Required Permission
Create Secret	`secret:write`
Read Secret (metadata)	`secret:read`
Read Secret (value)	`secret:read`
Update Secret	`secret:write`
Delete Secret	`secret:delete`
Archive / Restore	`secret:archive`
Permanent Delete	`secret:permanent_delete`
Rotate Secret	`rotation:execute`
Manage Rotation Config	`rotation:write`
Read Rotation Templates	`rotation:read`
Create / Update / Delete Rotation Templates	`rotation:write`
Read Sync / Links	`rotation:read`
Manage Links	`rotation:write`
Force Sync	`secret:write`

Getting Started — Authentication and base URL
Certificates API — Certificate management
Secrets Management Guide — UI-based guide

Secrets API¶

Endpoints Overview¶

Create Secret¶

Request Fields¶

Response 201 Created¶

Query Parameters¶

Response 200 OK¶

Get Secret¶

Response 200 OK¶

Update Secret¶

Updatable Fields¶

Response 200 OK¶

Delete Secret¶

Response 204 No Content¶

Archive & Restore¶

Archive Secret¶

Restore Secret¶

Permanent Delete¶

Copy Secret¶

Secret Versions¶

List Versions¶

Response 200 OK¶

Rollback Secret¶

Secret Rotation¶

Get Rotation Config¶

Update Rotation Config¶

Trigger Rotation¶

Response 200 OK¶

Synchronization¶

Get Sync Status¶

Response 200 OK¶

Force Sync¶

Force Sync (Per Environment)¶

Secret Links¶

List Links¶

Create Link¶

Delete Link¶

Rotation Template Catalog¶

Required Permissions¶

Related¶

Response `201 Created`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶

Response `204 No Content`¶

Response `200 OK`¶

Response `200 OK`¶

Response `200 OK`¶