> ## Documentation Index
> Fetch the complete documentation index at: https://syteca.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Syteca ACB Data Models
> Request and response schemas shared across Syteca ACB API endpoints — Permissions, Rotation, CheckOut, CheckPassword (heartbeat), SecretType, and the new password-status fields added in v1.4.
This page documents the request and response schemas that appear across multiple ACB endpoints. Field-by-field notes for each endpoint live on the [endpoint pages](/docs/api/acb/api-reference#endpoints); this page is the canonical reference for the **shared** schemas.
All field names use **snake\_case** (e.g. `parent_folder_id`, `rotate_every_min`). Boolean defaults are `false` unless otherwise noted.
## Enums
### SecretType
The type of credential a secret represents. Determines which other fields are required vs ignored.
| Value | Use case |
| ------------------- | ------------------------------------------------- |
| `None` | Default / uninitialized |
| `UnixAccountSSH` | SSH login to a Unix host (password or SSH key) |
| `UnixAccountTelnet` | Telnet login to a Unix host |
| `WindowsAccount` | Local Windows account login |
| `ADAccount` | Active Directory domain account |
| `WebAccount` | Web application login (URL + username + password) |
| `MSSQLAccount` | Microsoft SQL Server database login |
### PasswordRotationStatus
The state of rotation for a secret's password. Read-only in API responses.
| Value | Meaning |
| ---------- | ------------------------------------------ |
| `Disabled` | Rotation is not configured for this secret |
| `Enabled` | Rotation is configured and operational |
| `Failed` | Last rotation attempt failed |
### PasswordCheckStatus
The result of the last heartbeat password check on a secret. Read-only.
| Value | Meaning |
| --------- | ----------------------------------------------------------------- |
| `None` | No heartbeat check has been performed yet |
| `Valid` | The password is valid on the target endpoint |
| `Invalid` | The password is not valid (rotation may be needed) |
| `Failed` | The check itself failed (network error, target unreachable, etc.) |
### PasswordCheckPeriodType
Period type for heartbeat check intervals.
| Value | Meaning |
| -------- | ------------------------------------ |
| `Minute` | `check_every` is measured in minutes |
| `Hour` | `check_every` is measured in hours |
| `Day` | `check_every` is measured in days |
## Configuration objects
### Permissions
Container for the list of permissions granted on a folder or secret.
```json theme={"system"}
{
"permissions": [
{ /* see Permission */ }
]
}
```
### Permission
A single permission grant assigning a role to a user or user group on the resource.
| Field | Type | Description |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `user_id` | int | ID of the user receiving the permission. *(Mutually exclusive with `user_group_id`.)* |
| `user_group_id` | int | ID of the user group receiving the permission. *(Mutually exclusive with `user_id`.)* |
| `role` | string | One of `Owner`, `Editor`, `PAMUser`. See [Secret permissions → Role types](/docs/api/acb/secret-permissions#role-types). |
### AdditionalFeature
Optional features configurable per secret (e.g. file transfer access).
| Field | Type | Description |
| --------------- | ----------------------------- | ---------------------------------------------------- |
| `file_transfer` | [FileTransfer](#filetransfer) | File transfer feature configuration (Unix/SSH only). |
### FileTransfer
Configuration for file transfer alongside SSH sessions.
| Field | Type | Description |
| ------------------- | ------ | ------------------------------------------------- |
| `enabled` | bool | Whether file transfer is allowed for this secret. |
| `protocol` | string | One of `SFTP`, `SCP`. |
| `working_directory` | string | Initial working directory on the target. |
### Rotation
Password rotation configuration. **Changed in v1.4**: `rotate_every_min` is now required with `minimum: 1` — the v1.3 default of `0` (disabled) is no longer accepted in this field; use `enabled: false` instead.
| Field | Type | Description |
| ------------------ | ---- | ------------------------------------------------------- |
| `enabled` | bool | Whether rotation is enabled. **Required.** |
| `rotate_every_min` | int | Rotation interval in minutes (minimum 1). **Required.** |
### CheckOut
Check-out / check-in workflow configuration for shared secrets.
| Field | Type | Description |
| ------------------------ | ---- | ---------------------------------------------------------------------------------------------- |
| `enabled` | bool | Whether check-out is required to access the secret. **Required.** |
| `rotate_on_checkin` | bool | Whether to rotate the password automatically when the secret is checked back in. **Required.** |
| `auto_checkin_after_min` | int | Auto check-in timeout in minutes (default 60). **Required.** |
### CheckPassword
**NEW in v1.4** — Heartbeat password checking configuration.
| Field | Type | Description |
| ------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------ |
| `enabled` | bool | Whether heartbeat password checking is enabled. Default `false`. **Required.** |
| `check_every` | int | Interval for password check. Default `30`. **Required.** |
| `check_period_type` | [PasswordCheckPeriodType](#passwordcheckperiodtype) | Whether `check_every` is in minutes / hours / days. **Required.** |
### RequireApproval
Approval workflow configuration for high-sensitivity secrets.
| Field | Type | Description |
| --------------------- | ------ | ------------------------------------------------------- |
| `enabled` | bool | Whether approval is required to access this secret. |
| `approvers_user_ids` | int\[] | List of user IDs authorized to approve access requests. |
| `min_approvers_count` | int | Minimum number of approvers required. |
### PasswordData
Used in request bodies when setting a secret's password.
| Field | Type | Description |
| ---------- | ------ | ------------------- |
| `password` | string | The password value. |
### SshKey
Used in request bodies when setting a secret's SSH key (UnixAccountSSH type).
| Field | Type | Description |
| ------------- | ------ | ---------------------------------------- |
| `private_key` | string | The SSH private key contents. |
| `passphrase` | string | Optional passphrase for the private key. |
## Response shapes
### FolderResponseDto
Returned by `GET /api/folders/{id}` and `POST /api/folders`.
| Field | Type | Description |
| -------------------- | --------------------------- | ------------------------------------------ |
| `id` | int | Folder ID. |
| `name` | string | Folder name. |
| `description` | string | Folder description. |
| `parent_folder_id` | int | ID of the parent folder, or null for root. |
| `parent_folder_name` | string | Name of the parent folder. |
| `permissions` | [Permissions](#permissions) | Permission grants on this folder. |
### SecretPasswordlessResponseDto
Returned by `GET /api/secrets/{id}`, `POST /api/secrets`, and `PATCH /api/secrets/{id}`. **Does not include the actual password value** — to retrieve credentials use [Get secret credentials](/docs/api/acb/endpoints/get-secret-credentials).
| Field | Type | Description |
| ---------------------------- | ------------------------------------------------- | -------------------------------------------------------------- |
| `id` | int | Secret ID. |
| `name` | string | Secret name. |
| `type` | [SecretType](#secrettype) | Type of secret. |
| `description` | string | Secret description. |
| `parent_folder_id` | int | ID of the parent folder. |
| `domain` | string | AD domain (ADAccount type only). |
| `computer_name` | string | Target computer name (WindowsAccount type). |
| `url` | string | Web application URL (WebAccount type). |
| `server` | string | Server address (UnixAccount\* and MSSQLAccount types). |
| `login` | string | Login name. |
| `computers` | string\[] | List of computers this secret can be used on. |
| `file_transfer` | [FileTransfer](#filetransfer) | File transfer configuration. |
| `rotation` | [Rotation](#rotation) | Rotation configuration. |
| `record_activities` | bool | Whether to record session activities when this secret is used. |
| `check_out` | [CheckOut](#checkout) | Check-out workflow configuration. |
| `require_approval` | [RequireApproval](#requireapproval) | Approval workflow configuration. |
| `permissions` | [Permissions](#permissions) | Permission grants on this secret. |
| `check_password` | [CheckPassword](#checkpassword) | **NEW in v1.4** — Heartbeat check configuration. |
| `check_password_status` | [PasswordCheckStatus](#passwordcheckstatus) | **NEW in v1.4** — Result of last heartbeat check. |
| `last_password_check_utc` | datetime | **NEW in v1.4** — When the last heartbeat check ran. |
| `password_rotation_status` | [PasswordRotationStatus](#passwordrotationstatus) | **NEW in v1.4** — Current state of rotation. |
| `last_password_rotation_utc` | datetime | **NEW in v1.4** — When the password was last rotated. |
## Required vs ignored fields by SecretType
When creating a secret with [Add secret](/docs/api/acb/endpoints/add-secret), the relevance of each field depends on the `type` value:
| Field | UnixAccount\* | WindowsAccount | ADAccount | WebAccount | MSSQLAccount |
| ------------------------------ | ----------------- | -------------- | ------------ | ------------ | ------------ |
| `server` | **Required** | — | — | — | **Required** |
| `computer_name` | — | **Required** | — | — | — |
| `domain` | — | — | **Required** | — | — |
| `url` | — | — | — | **Required** | — |
| `login` | **Required** | **Required** | **Required** | **Required** | **Required** |
| `password` *(in PasswordData)* | Required (Telnet) | **Required** | **Required** | **Required** | **Required** |
| `ssh_key` *(in SshKey)* | Optional (SSH) | — | — | — | — |
| `file_transfer` | Optional (SSH) | — | — | — | — |
Fields marked `—` are ignored by the API for that secret type. See [Add secret](/docs/api/acb/endpoints/add-secret) for the per-type request examples.
## Related
Base URL, authentication, status codes, rate limiting.
The endpoint that consumes most of these schemas in request bodies.
Owner / Editor / PAM User roles and how they're applied.
The NEW v1.4 password-validity check endpoint.