--- title: "Activate the help desk" method: POST path: "/products/help-desk/activate" tags: ["help-desk"] --- # Activate the help desk `POST /products/help-desk/activate` ## Request - Base URL: `https://api.sparkvault.com/v1` - URL: `https://api.sparkvault.com/v1/products/help-desk/activate` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Turn the desk on in one of the organization's own vaults, presenting that vault's key. Presenting it is the consent: the help desk can then open every file in that vault, the ones already there included, on the organization's behalf, until it is deactivated. The first activation creates the settings, asking customers to sign in with Secure Identity when the organization's Identity serves sign-ins and with emailed codes otherwise. Activating again finishes an activation cut short, reactivates a deactivated desk, and moves an active desk that holds no requests yet to another vault; once it holds requests, they stay sealed in their vault. Org admins only, from their own session; the organization must hold the help desk and a handle, which names the desk's address. ## Request body - HelpDeskActivation - `vault_id` string, required: The vault the desk's requests are sealed in: one of the organization's own. - `vmk` string, required: That vault's key. Presenting it is the consent; it is verified, never stored. ## Response `200` The settings of the active desk. - object - `data` HelpDeskSettings, required: A help desk's settings, as its settings page reads them. - `vault_id` string, nullable, required: The vault the desk's requests are sealed in. - `activated_at` integer, nullable, required: Unix seconds: the last activation. Null while the first one has not finished. - `deactivated_at` integer, nullable, required: Unix seconds: the deactivation since the last activation. Null while the desk is active. - `customer_auth_preference` 'identity' | 'email_pin', required: How the desk asks its customers to sign in: identity (Secure Identity) or email_pin (a code mailed to them). GET /products/help-desk/settings/status says how they sign in now. - `operator_display` HelpDeskOperatorDisplay, required: How the desk shows its operators to customers. - `name_format` 'first_last_initial' | 'full_name' | 'generic', required: first_last_initial: the first name and last initial each operator sets (prefilled from their name); full_name: the member's name; generic: `generic_label` for everyone. An operator with no name to show shows `generic_label`. - `avatar_mode` 'authsv' | 'generic', required: authsv: each operator's Secure Identity avatar; generic: one silhouette for everyone. - `generic_label` string, required: The name shown where no operator's name is. - `status_after_reply` 'waiting_on_customer' | 'open', required: The status an operator's public reply moves a request to. - `auto_assign_on_first_reply` boolean, required: Whether the first operator to reply on an unassigned request is assigned it. - `customer_can_mark_resolved` boolean, required: Whether customers may close their own requests as resolved. - `feedback_positive_url` string, uri, nullable, required: Optional HTTPS follow-up link shown after a customer saves positive feedback. Null keeps the customer in the help desk. - `feedback_negative_url` string, uri, nullable, required: Optional HTTPS follow-up link shown after a customer saves negative feedback. No ticket or customer data is appended. - `email_content_mode` 'full' | 'notify_only', required: full: update emails carry the message; notify_only: they say only that the request changed, and link to it. - `accept_email_replies` boolean, required: Whether customers may answer by replying to an update email. - `custom_domain` string, nullable, required: The organization's own domain the desk answers at, beside its help.sv address; null for none. - `customer_upload_limit_bytes` integer, nullable, required: Maximum total pending and attached upload bytes per customer across all requests. Null (the default) leaves customer usage unlimited within the account storage plan. - `branding` object, required - `color` string, nullable, required: The portal's accent color, as #rrggbb; null for the default. - `version` integer, required: The version a change is made against (PUT /products/help-desk/settings). - `meta` ResponseMeta: Envelope metadata present on every successful response. - `api_version` string - `request_id` string - `response_ms` integer - `timestamp` integer: Unix seconds. - `pools` object: Storage and bandwidth capacity snapshot for the account. - `billing` object - `past_due` boolean - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise. - `limit` integer - `used` integer - `remaining` integer - `resets_at` integer: Unix seconds. ## Other responses - `400`: VALIDATION_ERROR — `vault_id` is no vault id, or `vmk` is missing or malformed. - `401`: AUTHENTICATION_ERROR — missing or invalid credentials. - `403`: FORBIDDEN — the caller is not an org admin, or the credential is an API key or an impersonated session. HELP_DESK_SUBSCRIPTION_REQUIRED — the organization does not hold the help desk. - `404`: NOT_FOUND — the vault is not one of the organization's own live vaults. - `409`: HANDLE_REQUIRED — the organization holds no handle yet. HELP_DESK_VAULT_IN_USE — the desk's requests are sealed in another vault (`details.vault_id`): activate it with that one. CONFLICT — the desk changed while the activation ran; try again. - `412`: PRECONDITION_FAILED — the key does not open this vault. - `503`: EMAIL_SETUP_BUSY — another request is setting up the organization's email (`Retry-After` carries 5 seconds), or email setup is busy right now; repeat the request in a moment. INTERNAL_ERROR — this deployment cannot send the help desk's email. ## Changes - **2026-10-28** `a9a10e328ba5`: 28 info - the response property `error/details` became required for the status `400` - the response property `error/details` became required for the status `401` - the response property `error/details` became required for the status `403` - the response property `error/details` became required for the status `404` - …24 more - **2026-10-28** `56d7c265a77a`: 7 breaking - the response property `error/details` became nullable for the status `400` - the response property `error/details` became nullable for the status `401` - the response property `error/details` became nullable for the status `403` - the response property `error/details` became nullable for the status `404` - …3 more - **2026-10-27** `ac44ec1f8cfa`: 1 breaking, 3 info - removed the required property `data/customer_storage_cap_bytes` from the response with the `200` status - added the required property `data/customer_upload_limit_bytes` to the response with the `200` status - added the required property `data/feedback_negative_url` to the response with the `200` status - added the required property `data/feedback_positive_url` to the response with the `200` status - **2026-10-22** `f5ac9c809ef7`: 1 info - endpoint added [Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/products/help-desk/activate/post.md) --- [API](https://skmtc.dev/sparkvault/apis/sparkvault-api.md) - [All operations](https://skmtc.dev/sparkvault/apis/sparkvault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sparkvault/apis/sparkvault-api/revisions/97cfadccd0c0?raw)