Skip to main content

Create or update Identity config

Create or update the user-level config for an Identity under the specified Template.

Request Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT>
Content-TypeYesapplication/json
Idempotency-KeyNoOptional idempotency key for requests with side effects.

Path parameters

ParameterTypeRequiredDescription
identity_idstringYesForward Identity ID.
template_idstringYesForward Template ID.

Request body

ParameterTypeRequiredDescription
namestringNoConfig display name.
identity_configobjectYesUser-level override configuration.
metadataobjectNoBusiness metadata; when provided, fully replaces existing metadata.

Identity Config object

identity_config is the stored user-level override DSL, not the compiled runtime config returned by Get Effective Config.
FieldInternal categoryDescription
systemAgentSystem prompt override or append rules.
modelAgentModel override.
toolsAgentBuilt-in tool overrides, organized by tool name.
mcp_serversAgentMCP Server overrides, organized by MCP server name.
skillsAgentSkill overrides, organized by Skill ID.
toolsetsAgentToolset-level overrides, mainly for MCP toolsets or built-in tool groups.
agent_metadataAgentMerged into the compiled Agent metadata.
vaultsSessionVault resource overrides, organized by Vault ID.
filesSessionFile resource overrides, organized by File ID; mount_path is injected by Forward and callers do not need to provide it.
environment / environment_idNot supportedIdentity Config cannot override the Template's execution environment; passing these fields returns 400 invalid_request_error.

Update semantics

Request formSemantics
Field absentKeep the existing value.
Field present with non-null valueUpdate this field.
Field present with value nullRemove this field from the current Identity Config.
metadata absentKeep the existing metadata.
metadata is an objectFully replace the existing metadata.
metadata is nullClear metadata.

Resource map semantics

skills, vaults, and files use the resource ID as the map key. Do not write skill_id, vault_id, file_id, id, or resource_id inside the entries; these runtime fields only appear in the Forward-compiled Effective Config.
Map entry valueSemantics
{ "enabled": true }Explicitly enable or override this resource.
{ "enabled": false }Explicitly disable this resource; even if present in the Template baseline it is removed or masked.
Entry absentInherit the Template baseline.
Entry value nullRemove the current override and restore inheritance from the Template baseline.

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_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "CRM profile",
  "identity_config": {
    "system": {
      "mode": "append",
      "content": "Prefer CRM data when answering."
    },
    "skills": {
      "skill_customer_reply": {
        "enabled": true,
        "type": "custom",
        "version": "1"
      },
      "skill_marketing_copy": {
        "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
      }
    },
    "vaults": {
      "vault_crm": {
        "enabled": true
      }
    },
    "files": {
      "file_019eXXXX": {
        "enabled": true
      }
    }
  },
  "metadata": {}
}'

Example response

HTTP 200 OK 
{
  "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

FieldTypeDescription
typestringAlways config.
identity_idstringForward Identity ID.
template_idstringForward Template ID.
effective_hashstringHash of the compiled Effective Config.

Errors

HTTPTypeCodeTrigger
400invalid_request_error-Invalid config field, unsupported Environment override, or invalid body.
404not_found_error-Identity, Template, Skill, Vault, or File does not exist.
409conflict_error-Config state conflict.
401authentication_errorauthentication_requiredPAT invalid or expired.

Notes

  • Omitted fields remain unchanged.
  • Passing a field as null removes it from the current Identity Config.
  • Resource maps use the resource ID as the key; setting a resource entry to null restores inheritance.
  • Identity Config currently does not support overriding environment_id.