Settings

Endpoints for managing workspace branding, API keys, and agent configuration.

Overview

Settings endpoints allow workspace admins to customize branding (which affects the widget appearance), manage API keys, and configure individual agent profiles. Most settings endpoints require the admin role.

Branding

Get Branding

GET/settings/branding

Get the current branding configuration for the workspace.

Auth: Workspace token (admin)

Response 200
{
  "workspaceName": "Acme Inc",
  "greeting": "Hey! How can we help you today?",
  "primaryColor": "#6366f1",
  "position": "bottom-right",
  "logoUrl": "https://cdn.zapticket.app/logos/ws_abc123.png",
  "showBranding": true,
  "requireEmail": false,
  "offlineMode": "ticket"
}

Update Branding

PUT/settings/branding

Update the workspace branding. All fields in the body are applied (full replace).

Auth: Workspace token (admin)

Request Body
{
  "workspaceName": "Acme Inc",
  "greeting": "Welcome to Acme! Ask us anything.",
  "primaryColor": "#10b981",
  "position": "bottom-right",
  "logoUrl": "https://cdn.zapticket.app/logos/ws_abc123.png",
  "showBranding": false,
  "requireEmail": true,
  "offlineMode": "hidden"
}
Response 200
{
  "workspaceName": "Acme Inc",
  "greeting": "Welcome to Acme! Ask us anything.",
  "primaryColor": "#10b981",
  "position": "bottom-right",
  "logoUrl": "https://cdn.zapticket.app/logos/ws_abc123.png",
  "showBranding": false,
  "requireEmail": true,
  "offlineMode": "hidden"
}
💡This is a PUT (full replace), not a PATCH. Send all branding fields, even those that haven't changed. Omitted fields will be reset to defaults.

API Keys

Get Keys

GET/settings/keys

Get the current API keys for the workspace.

Auth: Workspace token (admin)

Response 200
{
  "publicSiteKey": "zt_pub_abc123def456",
  "hmacSecret": "zt_hmac_••••••••••••",
  "hmacSecretLastRotated": "2024-01-01T09:00:00Z",
  "publicKeyLastRotated": "2024-01-01T09:00:00Z"
}
⚠️The HMAC secret is partially masked in the GET response for security. To see the full value, you must regenerate it — the full key is only shown at creation or regeneration time.

Regenerate Public Site Key

POST/settings/keys/regenerate-public

Regenerate the public site key. The old key stops working immediately.

Auth: Workspace token (admin)

Response 200
{
  "publicSiteKey": "zt_pub_new789ghi012",
  "regeneratedAt": "2024-01-15T12:00:00Z"
}
🚨Regenerating the public site key will immediately break any widget installations using the old key. Update your website's widget embed code after regenerating.

Regenerate HMAC Secret

POST/settings/keys/regenerate-hmac

Regenerate the HMAC secret used for visitor identity verification.

Auth: Workspace token (admin)

Response 200
{
  "hmacSecret": "zt_hmac_newsecret456abc",
  "regeneratedAt": "2024-01-15T12:00:00Z"
}
🚨Regenerating the HMAC secret invalidates all existing identity verification hashes. Update your server-side code that computes the hash before rotating this key.

Agent Settings

Update Agent Profile

PATCH/settings/agents/{id}

Update an agent's profile within the workspace.

Auth: Workspace token (admin, or the agent themselves)

Request Body
{
  "fullName": "Sarah Support Lead",
  "avatarUrl": "https://cdn.zapticket.app/avatars/new-photo.jpg",
  "role": "admin"
}

All fields are optional. Only send the fields you want to change.

Response 200
{
  "id": "agt_xyz789",
  "fullName": "Sarah Support Lead",
  "email": "[email protected]",
  "role": "admin",
  "avatarUrl": "https://cdn.zapticket.app/avatars/new-photo.jpg",
  "updatedAt": "2024-01-15T12:00:00Z"
}
💡Agents can update their own fullName and avatarUrl. Only admins can change the role field. Attempting to change your own role returns 403 Forbidden.