---
title: Dynamic Secrets
path: reference/dynamic
status: published
---

# Dynamic Secrets Reference

Endpoint reference for dynamic secrets engines, roles, and leases. For the guide, see [Dynamic Secrets](../api-guides/dynamic-secrets). For the model, see [Dynamic Secrets](../core-concepts/dynamic-secrets).

**Base path:** `/v1/dynamic/`

## Engines

### GET /v1/dynamic/engines

List engines.

**Scope:** `dynamic:read`.

### POST /v1/dynamic/engines

Create.

Body:

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Tenant-unique |
| `type` | Yes | `database`, `aws`, `azure`, `gcp`, `ssh`, `custom` |
| `config` | Yes | Engine-specific |
| `config.plugin` | For database | `postgresql`, `mysql`, `mongodb`, `redis` |
| `config.connection_url` | For database | Template with `{{username}}`, `{{password}}` |
| `config.root_credentials_path` | Yes | ScaiVault secret path |
| `default_ttl` | No | |
| `max_ttl` | No | |

Response: full engine with `connection_status`.

**Scope:** `dynamic:manage`.

### GET /v1/dynamic/engines/{name}

### PATCH /v1/dynamic/engines/{name}

Update config, TTLs.

### DELETE /v1/dynamic/engines/{name}

Returns `409 engine_in_use` if there are active leases. Revoke them first.

### POST /v1/dynamic/engines/{name}/test

Test the connection without creating anything.

## Roles

### GET /v1/dynamic/engines/{name}/roles

### POST /v1/dynamic/engines/{name}/roles

Body (database):

| Field | Description |
|-------|-------------|
| `name` | |
| `creation_statements` | Array of templated SQL |
| `revocation_statements` | Array of templated SQL |
| `default_ttl` | |
| `max_ttl` | |

Body (aws): `credential_type` (`iam_user` or `assumed_role`), `policy_document` or `policy_arns`, `role_arn` (for assume), TTLs.

Body (gcp): `service_account_email`, `roles`, TTLs.

### GET /v1/dynamic/engines/{name}/roles/{role}

### PATCH /v1/dynamic/engines/{name}/roles/{role}

### DELETE /v1/dynamic/engines/{name}/roles/{role}

## Credential Generation

### POST /v1/dynamic/engines/{name}/creds/{role}

Generate a lease.

Body:

| Field | Description |
|-------|-------------|
| `ttl` | Override default (bounded by `max_ttl`) |
| `metadata` | Custom annotations stored on the lease |

Response `201 Created`:

```json
{
  "lease_id": "lease_abc",
  "data": {
    "username": "v_readonly_a1b2c3",
    "password": "...",
    "connection_url": "...",
    "...": "..."
  },
  "lease_duration": "2h",
  "renewable": true,
  "expires_at": "2026-04-23T22:00:00Z"
}
```

**Scope:** `dynamic:generate`.

## Leases

### GET /v1/dynamic/leases

List. Query: `engine`, `role`, `status` (`active`|`expired`|`revoked`), `limit`, `cursor`.

**Scope:** `dynamic:read`.

### GET /v1/dynamic/leases/{lease_id}

Details, minus the original secret (returned only at creation).

### POST /v1/dynamic/leases/{lease_id}/renew

Body: `increment` (duration).

**Scope:** `dynamic:generate`.

### DELETE /v1/dynamic/leases/{lease_id}

Revoke immediately.

**Scope:** `dynamic:revoke`.

### POST /v1/dynamic/leases/revoke-prefix

Bulk revoke.

Body:

| Field | Description |
|-------|-------------|
| `prefix` | Lease ID prefix, e.g. `lease_db_` |
| `engine` | Optional engine name filter |
| `role` | Optional role name filter |

Response: `{"revoked": 47}`.

**Scope:** `dynamic:revoke`.

## Related

- [Dynamic Secrets Guide](../api-guides/dynamic-secrets)
- [Dynamic Secrets (Concepts)](../core-concepts/dynamic-secrets)