Create or update identity config

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	Internal target	Description
`system`	Agent	System prompt override or append rule.
`model`	Agent	Model override. Accepts a model ID string or an Agent model object.
`tools`	Agent	Built-in tool overrides keyed by tool name.
`mcp_servers`	Agent	MCP server overrides keyed by MCP server name.
`skills`	Agent	Skill overrides keyed by Skill ID.
`toolsets`	Agent	Toolset-level overrides, mainly for MCP toolsets or built-in tool groups.
`agent_metadata`	Agent	Metadata merged into the compiled agent metadata.
`vaults`	Session	Vault resource overrides keyed by Vault ID.
`files`	Session	File resource overrides keyed by File ID. Forward injects `mount_path`; callers do not provide it here.
`github_repositories`	Session	GitHub repository overrides keyed by an existing Template binding key or a new binding key.
`environment_variables`	Session	Session environment variable overrides keyed by variable name. Supports setting, removing, and inheriting Template defaults.
`environment` / `environment_id`	Unsupported	Identity Config cannot override the Template environment. Requests containing these fields fail with `400 invalid_request_error`.

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	Yes	Model ID. Use the list models endpoint to query available values.
`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`.

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/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
        }
      },
      "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

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

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`	`authentication_required`	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.
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

Model

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

​Model

​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

Model

GitHub repository overrides

Environment variable overrides

Update semantics

Resource map semantics

Example request

Example response

Response fields

Errors

Notes

Related