Copy

POST /api/v1/forward/identities/{identity_id}/templates/{template_id}/config Creates the config if it does not exist, or updates the existing active config. Identity Config is a user-level override over the Template baseline.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Optional idempotency key for unsafe requests.

Path parameters

Parameter	Type	Required	Description
`identity_id`	string	Yes	Forward Identity ID.
`template_id`	string	Yes	Forward Template ID.

Body parameters

Parameter	Type	Required	Description
`name`	string	No	Config display name.
`identity_config`	object	Yes	User-level override configuration.
`metadata`	object	No	Custom metadata. Replaces existing metadata when provided.

Identity config object

identity_config is the stored user-level override DSL. It is not the compiled runtime config returned by Get Effective Config.

Field	Type	Internal target	Description
`system`	object	Agent	System prompt override or append rule.
`model`	string \| object	Agent	Model override. Accepts a model ID string or an Agent model object.
`tools`	object \| array	Agent	Overrides tools by name (object), or replaces the runtime tools array. See Tools.
`managed_tool_config`	object	Forward managed capabilities	Sparse switches keyed by Capability or Bundle selector that override the Template Forward managed-capability baseline.
`mcp_servers`	object	Agent	MCP server overrides keyed by MCP server name.
`skills`	object	Agent	Skill overrides keyed by Skill ID.
`toolsets`	object	Agent	Toolset-level overrides, mainly for MCP toolsets or built-in tool groups.
`agent_metadata`	object	Agent	Metadata merged into the compiled agent metadata.
`vaults`	object	Session	Vault resource overrides keyed by Vault ID.
`files`	object	Session	File resource overrides keyed by File ID. Forward injects `mount_path`; callers do not provide it here.
`github_repositories`	object	Session	GitHub repository overrides keyed by an existing Template binding key or a new binding key.
`environment_variables`	object	Session	Session environment variable overrides keyed by variable name. Supports setting, removing, and inheriting Template defaults.
`environment` / `environment_id`	Unsupported	Unsupported	Identity Config cannot override the Template environment. Requests containing these fields fail with `400 invalid_request_error`.

All supported override fields accept null to remove the current override and restore inheritance. When updating an existing Config, objects merge recursively by field and arrays replace the previous array. See Update semantics.

System

identity_config.system is an object; the compiled agent.system is a string.

Field	Type	Required	Description
mode	string	No	`replace` or `append`. Defaults to `replace` if the override has no `mode`.
content	string	No	Prompt text. Leading and trailing whitespace is trimmed during compilation. If absent from the override, it is treated as an empty string.

replace replaces the Template prompt with content; an empty string clears it. append trims both prompts and joins them with one newline when both are nonempty. Empty appended content preserves a nonempty Template prompt. For a Template prompt of You are a support assistant., appending Prefer CRM data when answering. produces You are a support assistant.\nPrefer CRM data when answering.. With replace, the result is only Prefer CRM data when answering.. Updating only content preserves the stored mode; it does not reset an existing append to replace. Set mode explicitly to change it. system: null removes the entire System override and restores the Template prompt. Invalid modes such as prepend return 400 invalid_request_error.

{
  "identity_config": {
    "system": {
      "mode": "append",
      "content": "Prefer CRM data when answering."
    }
  }
}

Model

identity_config.model accepts either a model ID string or an object containing a model ID and optional tuning fields.

Field	Type	Required	Description
`id`	string	Conditional	Model ID. Required when first setting a model object. When updating an existing object, it can be omitted to inherit `id` from the stored model override.
`effort`	string	No	Reasoning effort. Values: `none`, `low`, `medium`, `high`, `xhigh`, or `max`. Check the model's `efforts` field for supported values.
`context_window`	integer	No	Requested context window in tokens. Must be a positive integer selected from the model's `available_context_windows`.
`speed`	string	No	Inference speed: `standard` or `high`. Uses `standard` if the final model does not set this field. See the `speed` array returned by List models for supported values.

Tools

identity_config.tools accepts an object or an array:

Object: keys are tool names and values override Template tool configuration. Built-in names are listed in Agent schemas.
Array: replaces the entire Template tools array; items use Agent tool. Include every tool you want to retain. [] means no tools. toolsets overrides are still applied afterward.

Object field	Type	Required	Description
enabled	boolean	No	Compiles as `true` when omitted. `false` hides and denies the tool.
permission_policy	object	No	Permission policy, with `type` set to `always_allow`, `always_ask`, or `always_deny`.

Object form can also enable or disable existing Template custom tools by name, but those entries support only enabled. Use array form to add or modify custom-tool definitions.

{
  "identity_config": {
    "tools": {
      "Bash": {
        "enabled": true,
        "permission_policy": { "type": "always_ask" }
      },
      "WebSearch": { "enabled": false }
    }
  }
}

Toolsets

identity_config.toolsets is keyed by toolset identifier. Use agent_toolset_20260401 for the built-in toolset. For MCP toolsets, prefer the server name as the key and specify type and mcp_server_name explicitly.

Field	Type	Required	Description
type	string	No	`agent_toolset_20260401` or `mcp_toolset`; explicit configuration is recommended.
enabled	boolean	No	Defaults to `true`. `false` removes the whole toolset from the effective tools.
mcp_server_name	string	Recommended for MCP	MCP server name. With `type: "mcp_toolset"`, omission uses the map key.
tools	object	No	Tool-name-keyed overrides supporting `enabled` and `permission_policy`. Use original MCP tool names exposed by the server, without an `mcp__` prefix.
configs	array	No	Runtime Tool config array. When provided, replaces inherited `configs`. Normally use `tools` for per-tool overrides.

toolsets.*.tools compiles into agent.tools[].configs, merged by tool name; untouched configurations remain. If both configs and tools are supplied, the configs array is used first and tools is applied afterward. If the same built-in tool appears in the top-level tools object and in toolsets, the top-level tools object is applied last.

{
  "identity_config": {
    "toolsets": {
      "mcp_crm": {
        "type": "mcp_toolset",
        "mcp_server_name": "mcp_crm",
        "tools": {
          "search_customers": { "enabled": true },
          "delete_customer": {
            "enabled": true,
            "permission_policy": { "type": "always_ask" }
          }
        }
      }
    }
  }
}

The example requires an MCP server named mcp_crm in the Template or Identity Config.

MCP servers

identity_config.mcp_servers is keyed by MCP server name. The map key becomes name in the compiled agent.mcp_servers[].

Field	Type	Required	Description
enabled	boolean	No	Defaults to `true`. `false` removes an inherited server.
type	string	No	Forward uses `http`. New entries default to `http`; overrides inherit the existing type.
url	string	For new entries	Streamable HTTP MCP endpoint URL. Overrides can inherit the Template URL.

Configure MCP authentication through a Vault, then bind it through vaults.

Skills

identity_config.skills is keyed by Skill ID. Compilation fills in skill_id in agent.skills[].

Field	Type	Required	Description
enabled	boolean	No	Defaults to `true`. `false` disables an inherited Skill.
type	string	No	`custom` or `qoder`. New entries default to `custom`; overrides inherit the existing type.
version	string	No	Nonempty version string. Overrides inherit the existing version; if the final configuration has no version, the latest version is used.

Vaults and Files

identity_config.vaults and identity_config.files are keyed by Vault ID and File ID respectively. Each entry supports optional boolean enabled, defaulting to true; false disables a resource inherited from the Template. For example, "vaults": {"vault_019f18f2761b": {"enabled": true}} enables the Vault. Compiled Vault IDs go into session.vault_ids; files go into session.resources. Forward injects file mount paths, so callers do not supply mount_path.

Forward managed-capability overrides

The Template provides the complete Capability/Bundle selector baseline through the top-level managed_tool_config.enabled_tools. Identity Config stores only the sparse switches that need to change in identity_config.managed_tool_config. Forward provides the tools for the effective capabilities; you do not need to configure their implementations in tools. Omitted selectors inherit the Template baseline, so adding capabilities to the Template later does not require backfilling existing Identity Configs.

{
  "identity_config": {
    "managed_tool_config": {
      "schedule": {
        "enabled": false
      },
      "drive": {
        "enabled": true
      }
    }
  }
}

Request shape	Semantics
A selector set to `{ "enabled": true }`	Explicitly enables the corresponding managed capabilities for this Identity.
A selector set to `{ "enabled": false }`	Explicitly disables the corresponding managed capabilities for this Identity.
Selector omitted	Keeps the stored override for that selector, or inherits from the Template if no override exists.
A selector set to `null`	Removes that selector's override and restores Template inheritance.
`managed_tool_config: {}`	Does not change stored individual overrides.
`managed_tool_config: null`	Clears all Forward managed-capability overrides and restores Template inheritance.

Supported selectors are:

Selector	Semantics
`schedule`	Schedule capability bundle that controls creating, listing, and deleting Schedules together.
`create_forward_schedule`	Controls only Schedule creation.
`list_forward_schedules`	Controls only Schedule listing.
`delete_forward_schedule`	Controls only Schedule deletion.
`drive`	Controls the complete Drive capability.

Each value must be an object containing only a boolean enabled field. Identity sparse overrides do not accept the Template's enabled_tools array. Unknown selectors, extra fields, a missing enabled field, or an invalid type return HTTP 400. Execution tool names for drive, such as list_drive_entries, cannot be used directly as selectors. When schedule and fine-grained Schedule selectors appear in the same Identity Config, the schedule value takes precedence. For example, schedule.enabled=false disables all three Schedule capabilities even if list_forward_schedules.enabled=true is set in the same layer. When schedule is not set, fine-grained selectors can individually override Schedule capabilities inherited from the Template. Setting schedule to null removes only the bundle override; it does not remove stored fine-grained overrides.

GitHub repository overrides

identity_config.github_repositories is a keyed overlay. It can override a binding inherited from the Template or add a new binding.

Field	Type	Description
`url`	string\|null	Override the inherited repository's HTTPS URL. Validation and normalization match the Template rules.
`authorization_token`	string\|null	Override the repository access token. This field is write-only and is not returned by read APIs.
`mount_path`	string\|null	Override the session mount path. A non-empty value must be a normalized absolute path other than `/`. `null` removes the field override. If Effective Config has no inherited path, the default is `/data/workspace/<repository-name>`.
`enabled`	boolean\|null	`false` disables the binding, `true` explicitly enables it, and `null` removes this field override.

Request shape	Semantics
`github_repositories` omitted	Keep the current repository overlay.
`github_repositories: null`	Remove the entire repository overlay and restore Template inheritance.
Binding omitted	Keep the existing override, or inherit from the Template if no override exists.
Binding set to `null`	Remove the binding override and restore Template inheritance.
Binding `enabled` set to `false`	Disable the inherited binding with the same key.
Binding set to an object	Merge the fields into the binding with the same key.

The resulting Effective Config can contain up to 20 enabled bindings. If a same-key binding omits mount_path, it inherits the Template value. A new binding with no inherited path defaults to /data/workspace/<repository-name>. Every enabled binding must resolve to a valid url, authorization_token, and mount_path. Normalized URLs and mount paths must be unique.

Environment variable overrides

identity_config.environment_variables is an override object keyed by environment variable name.

{
  "identity_config": {
    "environment_variables": {
      "BASE_MODE": {
        "op": "set",
        "value": "identity"
      },
      "REMOVE_ME": {
        "op": "unset"
      },
      "USER_MODE": {
        "op": "set",
        "value": "enabled"
      }
    }
  }
}

Request shape	Semantics
`{ "op": "set", "value": "..." }`	Add a variable or override the same variable from the Template.
`{ "op": "unset" }`	Remove the variable from Effective Config even if the Template defines it.
Variable omitted	Keep the existing Identity Config override, or inherit from the Template if no override exists.
Variable set to `null`	Remove that variable's Identity Config override and restore Template inheritance.
`environment_variables: null`	Remove the entire environment-variable override layer and restore all Template defaults.

Update semantics

Request shape	Semantics
Field omitted	Keep the existing value.
Field present with a non-null value	Update that field.
Field present with `null`	Remove that field from the current Identity Config.
`metadata` omitted	Keep existing metadata.
`metadata` object	Replace existing metadata.
`metadata` `null`	Clear metadata.

Resource map semantics

skills, vaults, and files use resource IDs as map keys. Do not include skill_id, vault_id, file_id, id, or resource_id inside the map item. Those runtime fields only appear in the Effective Config compiled by Forward.

Map item value	Semantics
`{ "enabled": true }`	Explicitly enable or override the resource.
`{ "enabled": false }`	Explicitly disable the resource, even if it exists in the Template baseline.
Item omitted	Inherit the Template baseline.
Item value `null`	Delete this override and restore Template inheritance.

Example request

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/identities/idn_019eabc123/templates/tmpl_support/config' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM profile",
    "identity_config": {
      "model": {
        "id": "ultimate",
        "effort": "high",
        "context_window": 400000
      },
      "system": {
        "mode": "append",
        "content": "Prefer CRM data when answering."
      },
      "skills": {
        "skill_019f18f2749e": {
          "enabled": true,
          "type": "custom",
          "version": "1"
        },
        "skill_019f18f2750a": {
          "enabled": false
        }
      },
      "mcp_servers": {
        "mcp_crm": {
          "enabled": true,
          "type": "http",
          "url": "https://crm.example.com/mcp"
        }
      },
      "tools": {
        "Read": {
          "enabled": true
        },
        "Grep": {
          "enabled": true
        },
        "WebSearch": {
          "enabled": true
        }
      },
      "managed_tool_config": {
        "schedule": {
          "enabled": false
        },
        "drive": {
          "enabled": true
        }
      },
      "vaults": {
        "vault_019f18f2761b": {
          "enabled": true
        }
      },
      "files": {
        "file_019eXXXX": {
          "enabled": true
        }
      },
      "environment_variables": {
        "CRM_REGION": {
          "op": "set",
          "value": "cn-shanghai"
        },
        "LEGACY_CRM_MODE": {
          "op": "unset"
        }
      },
      "github_repositories": {
        "source": {
          "mount_path": "/data/workspace/support-agent",
          "authorization_token": "github_pat_xxx"
        },
        "legacy": {
          "enabled": false
        }
      }
    },
    "metadata": {}
  }'

Example response

Creating a Config for the first time returns HTTP 201 Created; updating an existing Config returns HTTP 200 OK. Both responses have the same body structure.

{
  "type": "config",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "name": "CRM profile",
  "status": "active",
  "effective_hash": "sha256:...",
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:00:00Z"
}

Response fields

Field	Type	Description
`type`	string	Always `config`.
`identity_id`	string	Forward Identity ID.
`template_id`	string	Forward Template ID.
`name`	string	Config display name.
`status`	string	Config status.
`effective_hash`	string	Hash of the compiled effective config.
`created_at`	string	Creation timestamp.
`updated_at`	string	Update timestamp.

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	-	A config field, GitHub binding structure, or field value is invalid; an unsupported Environment override is provided; or the request body is invalid.
401	`authentication_error`	-	The PAT or SAT is invalid or expired.
404	`not_found_error`	-	The Identity, Template, Skill, Vault, or File does not exist.
409	`conflict_error`	-	The Config state conflicts, or normalized URLs or mount paths in the effective GitHub repositories are duplicated.

Notes

Omitted config fields remain unchanged.
A field set to null removes that field from the current Identity Config.
managed_tool_config is a sparse merge by selector, not a complete array replacement.
Resource maps use their resource ID as the map key. To restore inheritance for one resource, set that map entry to null.
Identity Config does not support overriding environment_id.
identity_config.github_repositories.*.authorization_token is write-only and is not returned in Config or Effective Config responses.

Create or update identity config

Headers

Path parameters

Body parameters

Identity config object

System

Model

Tools

Toolsets

MCP servers

Skills

Vaults and Files

Forward managed-capability overrides

GitHub repository overrides

Environment variable overrides

Update semantics

Resource map semantics

Example request

Example response

Response fields

Errors

Notes

Get identity config

Get effective config

​Headers

​Path parameters

​Body parameters

​Identity config object

​System

​Model

​Tools

​Toolsets

​MCP servers

​Skills

​Vaults and Files

​Forward managed-capability overrides

​GitHub repository overrides

​Environment variable overrides

​Update semantics

​Resource map semantics

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

Get identity config

Get effective config

Headers

Path parameters

Body parameters

Identity config object

System

Model

Tools

Toolsets

MCP servers

Skills

Vaults and Files

Forward managed-capability overrides

GitHub repository overrides

Environment variable overrides

Update semantics

Resource map semantics

Example request

Example response

Response fields

Errors

Notes

Related