Vault object
Create, get, list, and archive endpoints return this structure.
| Field | Type | Description |
|---|
id | string | Vault ID with the vault_ prefix |
type | string | Always "vault" |
display_name | string | Vault display name, at most 255 characters |
metadata | object | Custom metadata stored with the Vault; defaults to {} when omitted. created_by is reserved by Forward and must not be supplied by callers |
archived_at | string | null | Archive time in RFC 3339 format; null while active |
created_at | string | Creation time in RFC 3339 format |
updated_at | string | Last update time in RFC 3339 format |
identity_id | string | null | Owning Forward identity. Returns the Identity ID for an Identity-owned resource, or null otherwise. See Identity ownership. |
icon_url | string | null | Icon URL associated by Forward |
binding_info | Binding info | Binding information, such as Template reference counts |
Identity ownership
An account (or Workspace) can have multiple Identities. Each Identity represents an end user of the product integrated with that account (or Workspace).
A Vault can belong to the account (or Workspace) or to an Identity. Ownership determines who can see and operate it.
Selecting ownership
| Caller | Owner | How to select |
|---|
| PAT | Account / Workspace | Omit identity_id (the default, unchanged behavior). |
| PAT | A specific Identity | Pass the query parameter identity_id=<identity_id>. |
| Admin SAT | Workspace | Resolved automatically; parameters cannot switch ownership. |
| Identity-bound SAT | The bound Identity | Resolved automatically; parameters cannot switch ownership. |
identity_id is optional and is used only for Identity-owned resources. A PAT can specify it explicitly; omitting it uses the administrator scope. With SAT, issue an Identity-scoped token and do not explicitly pass this parameter, even with an empty value. Doing so returns HTTP 400.
An Identity specified with a PAT must belong to the account or Workspace represented by that PAT and must be enabled. A nonexistent, disabled, deleted, or foreign Identity returns 404.
Ownership isolation
- Calls in the account or Workspace scope cannot see Identity-owned Vaults.
- An Identity cannot see Vaults owned by the account (or Workspace) itself or by other Identities in the same account.
- In a valid Identity scope (a PAT with a valid
identity_id, or an Identity SAT), cross-scope get-by-ID, update, archive, and delete operations return 404, without distinguishing a nonexistent resource from a resource owned by someone else.
- PAT calls without
identity_id and Admin SAT calls retain the existing behavior: an Owner mismatch returns 403.
Supported endpoints
Create, search, list, get, update, archive, and delete Vault endpoints support the identity_id query parameter.
Vault credentials inherit ownership entirely from their Vault. See Credential identity ownership.
GET /api/v1/forward/resources/batch does not yet support identity_id. Its visibility rules are unchanged.
Binding info
Reference summary included by Forward in Vault responses.
| Field | Type | Description |
|---|
agent_template_count | integer | Number of Templates currently bound to the Vault |
| Field | Type | Description |
|---|
data | array of Vault objects | Records on the current page |
has_more | boolean | Whether another page is available |
next_page | string | null | Forward cursor for the next page (recommended). Equals the current page's last_id when has_more=true; otherwise null |
first_id | string | null | ID of the first record on the current page |
last_id | string | null | ID of the last record on the current page |
page, after_id, and before_id are mutually exclusive; providing more than one returns 400. Use page where possible; it has the same semantics as after_id.
