Forward API reference.
Vault credential object
Create, update, get, list, and archive endpoints return this structure. Credential secrets such as token, access_token, refresh_token, client_secret, and secret_value are accepted only in create or update requests and are never returned in responses.
| Field | Type | Description |
|---|---|---|
id | string | Credential ID with the vcred_ prefix |
type | string | Always "vault_credential" |
vault_id | string | Owning Vault ID |
auth | Credential auth object | Sanitized auth details; secrets are never returned |
display_name | string | Compatibility field. Currently always an empty string and not persisted |
metadata | object | Custom metadata object stored with the credential; defaults to {} |
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 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 Credential does not store ownership separately. It inherits ownership entirely from its Vault:
- Before accessing a Credential, the service checks its Vault against the current ownership scope. In a valid Identity scope, a Vault owned by another Identity returns
404. PAT calls withoutidentity_idand Admin SAT calls retain the existing Owner mismatch403. If this check fails, Credential processing does not continue. - Every Credential in an Identity-owned Vault is visible only to that Identity.
- Create, list, get, update, archive, and delete Credential endpoints support the
identity_idquery parameter with the same semantics as Vaults. See Vault identity 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; otherwise, the request returns HTTP 400.
Create credential request
| Field | Type | Required | Description |
|---|---|---|---|
auth | Credential auth object | Yes | Credential authentication information |
metadata | object | No | Custom metadata stored with the credential; defaults to {} |
Update credential request
Only auth and metadata are accepted, and at least one field is required. Other fields return 400 invalid_request_error.
| Field | Type | Required | Description |
|---|---|---|---|
auth | object | No | Partially updates authentication information. It must include a type that matches the current Credential type |
metadata | object | null | No | Merge patch. A null value in the object removes that key; top-level null clears all metadata |
Credential auth object
auth uses type to select the authentication type. Responses never include secret fields.
static_bearer
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Always "static_bearer" |
mcp_server_url | string | Yes | MCP server URL, at most 2048 characters |
token | string | Yes (request) | Static Bearer token. Accepted only in create requests and never returned in responses |
mcp_oauth
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Always "mcp_oauth" |
mcp_server_url | string | Yes | MCP server URL, at most 2048 characters |
client_id | string | Yes | OAuth client ID |
client_secret | string | Yes (request) | OAuth client secret. Accepted only in create requests and never returned in responses |
access_token | string | No (request) | Access token already obtained through OAuth. Accepted only in create requests and never returned in responses |
refresh_token | string | No (request) | OAuth refresh token. Accepted only in create requests and never returned in responses |
environment_variable
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Always "environment_variable" |
secret_name | string | Yes (create request) | Environment variable name. Must match [A-Za-z_][A-Za-z0-9_]* and cannot be changed after creation |
secret_value | string | Yes (create request) | Environment variable value. Accepted in create or update requests and never returned in responses |
injection_location | object | No | Injection location configuration. It can contain the boolean fields body and header |
networking | object | No | Network access constraint. Supports unrestricted or limited with allowed_hosts |
The create endpoint for the Forward Credential API defines the supported authentication types. Unlisted types return 400 invalid_request_error during creation.
List pagination fields
| Field | Type | Description |
|---|---|---|
data | array of Vault credential 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.