## Create (version 0) or change desk's app settings of the customer portal at their version (desk:admin)

`PUT /api/desk/v1/portal-config`

Module: Desk · operationId: `setPortalConfig` · Tag: Portal · Auth: access token (`Authorization: Bearer <accessToken>`)

### Request body

`application/json` (required)

- `settings` (object, required): Settings of desk's portal apps
  - `agentName` (string): How agents are named to requesters: full name, first name or „Support“ (one of `full`, `first`, `support`)
  - `attachments` (object): File limits of requester uploads
    - `allowedMime` (array of string): Allowed MIME types of requester uploads
    - `maxBytes` (integer): Maximum size per file in bytes
    - `maxCount` (integer): Maximum number of files
  - `companyView` (object): Allows the company view; who has it is set on the customer account (customerportal)
    - `enabled` (boolean): The company view may be granted
  - `forms` (array of object): Forms requesters open tickets with
    - `key` (string, required): Key of the form
    - `label` (string, required): Name of the form (max length 80)
    - `spaceKey` (string, required): Space of the tickets
    - `typeKey` (string, required): Type of the tickets
    - `defaultPriority` (string): Priority key of the tickets
    - `description` (string): Description shown with the form
    - `fields` (array of object): Fields of the form
      - `key` (string, required): cf.<key>
      - `help` (string): Help text
      - `label` (string): Label shown to the requester
      - `required` (boolean): The requester must fill it
    - `public` (object): Opens the form for submissions without sign-in
      - `enabled` (boolean): Submissions without sign-in are on
      - `key` (string, read-only): Generated; names the form in the public URL (not secret)
      - `origins` (array of string): Sites that may embed the form, like https://www.example.de; * any
  - `help` (object): Help area settings
    - `ask` (boolean): Requesters may ask questions answered from the released articles; missing is on
  - `limits` (object): Limits per requester
    - `entriesPerHour` (integer): Replies per requester and hour
    - `ticketsPerDay` (integer): New tickets per requester and day
  - `phaseLabels` (object): Names for requesters by phase (fallback)
  - `platformFeedback` (object): Platform feedback targets per kind; only the operator tenant (10639/MBCOM) may enable kinds
    - `kinds` (object): Keys: bug, feature, emergency, account
  - `satisfaction` (object): Customer satisfaction: the requester rates a closed ticket once (1–5 stars, optional comment) within `days` after it was closed (`rateCustomerTicket`; event `desk.ticket.rated`)
    - `days` (integer): Days after closing; missing or 0 is 14 (max 90)
    - `enabled` (boolean): Requesters may rate closed tickets
  - `statusLabels` (object): Names for requesters by "<workflowKey>:<statusKey>"; the key "forwarded" names forwarding stubs (default „Weitergeleitet“)
  - `types` (object): Per type key: visible to requesters, fields they see (priority, dueAt, customer, contact, category, startOn, cf.<key>)
- `platformAvailable` (boolean, read-only): This tenant is the operator tenant
- `portalUrl` (string, read-only): Address of the tenant's customer portal (from customerportal); missing without one
- `updatedAt` (string (date-time), read-only): When they were last saved
- `updatedBy` (string, read-only): Login (e-mail) of who last saved them
- `version` (integer): Version of the settings (0: never saved); send it back on change

Example:

```json
{
  "platformAvailable": false,
  "portalUrl": "https://muster-it.connectcloud.example",
  "settings": {
    "agentName": "full",
    "attachments": {
      "allowedMime": [
        "image/png",
        "image/jpeg",
        "application/pdf"
      ],
      "maxBytes": 10485760,
      "maxCount": 5
    },
    "companyView": {
      "enabled": true
    },
    "forms": [
      {
        "defaultPriority": "normal",
        "description": "Etwas funktioniert nicht? Beschreiben Sie kurz, was passiert ist.",
        "fields": [
          {
            "help": "z. B. Drucker Empfang",
            "key": "cf.betroffenes_system",
            "label": "Betroffenes Gerät oder System",
            "required": false
          }
        ],
        "key": "stoerung",
        "label": "Störung melden",
        "public": {
          "enabled": false
        },
        "spaceKey": "SUP",
        "typeKey": "stoerung"
      }
    ],
    "help": {
      "ask": true
    },
    "limits": {
      "entriesPerHour": 30,
      "ticketsPerDay": 20
    },
    "phaseLabels": {
      "active": "In Bearbeitung",
      "done": "Erledigt",
      "new": "Eingegangen",
      "waiting": "Wartet auf Rückmeldung"
    },
    "satisfaction": {
      "days": 14,
      "enabled": true
    },
    "statusLabels": {},
    "types": {
      "serviceanfrage": {
        "fields": [
          "priority",
          "category",
          "dueAt"
        ],
        "visible": true
      },
      "stoerung": {
        "fields": [
          "priority",
          "category",
          "cf.betroffenes_system"
        ],
        "visible": true
      }
    }
  },
  "updatedAt": "2026-10-28T10:15:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 5
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Invalid
- **409** Version conflict

Fields of the 200 answer:

- `settings` (object, required): Settings of desk's portal apps
  - `agentName` (string): How agents are named to requesters: full name, first name or „Support“ (one of `full`, `first`, `support`)
  - `attachments` (object): File limits of requester uploads
    - `allowedMime` (array of string): Allowed MIME types of requester uploads
    - `maxBytes` (integer): Maximum size per file in bytes
    - `maxCount` (integer): Maximum number of files
  - `companyView` (object): Allows the company view; who has it is set on the customer account (customerportal)
    - `enabled` (boolean): The company view may be granted
  - `forms` (array of object): Forms requesters open tickets with
    - `key` (string, required): Key of the form
    - `label` (string, required): Name of the form (max length 80)
    - `spaceKey` (string, required): Space of the tickets
    - `typeKey` (string, required): Type of the tickets
    - `defaultPriority` (string): Priority key of the tickets
    - `description` (string): Description shown with the form
    - `fields` (array of object): Fields of the form
      - `key` (string, required): cf.<key>
      - `help` (string): Help text
      - `label` (string): Label shown to the requester
      - `required` (boolean): The requester must fill it
    - `public` (object): Opens the form for submissions without sign-in
      - `enabled` (boolean): Submissions without sign-in are on
      - `key` (string, read-only): Generated; names the form in the public URL (not secret)
      - `origins` (array of string): Sites that may embed the form, like https://www.example.de; * any
  - `help` (object): Help area settings
    - `ask` (boolean): Requesters may ask questions answered from the released articles; missing is on
  - `limits` (object): Limits per requester
    - `entriesPerHour` (integer): Replies per requester and hour
    - `ticketsPerDay` (integer): New tickets per requester and day
  - `phaseLabels` (object): Names for requesters by phase (fallback)
  - `platformFeedback` (object): Platform feedback targets per kind; only the operator tenant (10639/MBCOM) may enable kinds
    - `kinds` (object): Keys: bug, feature, emergency, account
  - `satisfaction` (object): Customer satisfaction: the requester rates a closed ticket once (1–5 stars, optional comment) within `days` after it was closed (`rateCustomerTicket`; event `desk.ticket.rated`)
    - `days` (integer): Days after closing; missing or 0 is 14 (max 90)
    - `enabled` (boolean): Requesters may rate closed tickets
  - `statusLabels` (object): Names for requesters by "<workflowKey>:<statusKey>"; the key "forwarded" names forwarding stubs (default „Weitergeleitet“)
  - `types` (object): Per type key: visible to requesters, fields they see (priority, dueAt, customer, contact, category, startOn, cf.<key>)
- `platformAvailable` (boolean, read-only): This tenant is the operator tenant
- `portalUrl` (string, read-only): Address of the tenant's customer portal (from customerportal); missing without one
- `updatedAt` (string (date-time), read-only): When they were last saved
- `updatedBy` (string, read-only): Login (e-mail) of who last saved them
- `version` (integer): Version of the settings (0: never saved); send it back on change

Example 200 answer:

```json
{
  "platformAvailable": false,
  "portalUrl": "https://muster-it.connectcloud.example",
  "settings": {
    "agentName": "full",
    "attachments": {
      "allowedMime": [
        "image/png",
        "image/jpeg",
        "application/pdf"
      ],
      "maxBytes": 10485760,
      "maxCount": 5
    },
    "companyView": {
      "enabled": true
    },
    "forms": [
      {
        "defaultPriority": "normal",
        "description": "Etwas funktioniert nicht? Beschreiben Sie kurz, was passiert ist.",
        "fields": [
          {
            "help": "z. B. Drucker Empfang",
            "key": "cf.betroffenes_system",
            "label": "Betroffenes Gerät oder System",
            "required": false
          }
        ],
        "key": "stoerung",
        "label": "Störung melden",
        "public": {
          "enabled": false
        },
        "spaceKey": "SUP",
        "typeKey": "stoerung"
      }
    ],
    "help": {
      "ask": true
    },
    "limits": {
      "entriesPerHour": 30,
      "ticketsPerDay": 20
    },
    "phaseLabels": {
      "active": "In Bearbeitung",
      "done": "Erledigt",
      "new": "Eingegangen",
      "waiting": "Wartet auf Rückmeldung"
    },
    "satisfaction": {
      "days": 14,
      "enabled": true
    },
    "statusLabels": {},
    "types": {
      "serviceanfrage": {
        "fields": [
          "priority",
          "category",
          "dueAt"
        ],
        "visible": true
      },
      "stoerung": {
        "fields": [
          "priority",
          "category",
          "cf.betroffenes_system"
        ],
        "visible": true
      }
    }
  },
  "updatedAt": "2026-10-28T10:15:00Z",
  "updatedBy": "elias.gruber@muster-it.example",
  "version": 5
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/portal-config' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"platformAvailable":false,"portalUrl":"https://muster-it.connectcloud.example","settings":{"agentName":"full","attachments":{"allowedMime":["image/png","image/jpeg","application/pdf"],"maxBytes":10485760,"maxCount":5},"companyView":{"enabled":true},"forms":[{"defaultPriority":"normal","description":"Etwas funktioniert nicht? Beschreiben Sie kurz, was passiert ist.","fields":[{"help":"z. B. Drucker Empfang","key":"cf.betroffenes_system","label":"Betroffenes Gerät oder System","required":false}],"key":"stoerung","label":"Störung melden","public":{"enabled":false},"spaceKey":"SUP","typeKey":"stoerung"}],"help":{"ask":true},"limits":{"entriesPerHour":30,"ticketsPerDay":20},"phaseLabels":{"active":"In Bearbeitung","done":"Erledigt","new":"Eingegangen","waiting":"Wartet auf Rückmeldung"},"satisfaction":{"days":14,"enabled":true},"statusLabels":{},"types":{"serviceanfrage":{"fields":["priority","category","dueAt"],"visible":true},"stoerung":{"fields":["priority","category","cf.betroffenes_system"],"visible":true}}},"updatedAt":"2026-10-28T10:15:00Z","updatedBy":"elias.gruber@muster-it.example","version":5}'
```
