Kenso MCP tools

Permissions permissions

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through permissions_read and changes through permissions_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.

Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.

Operations: access-requests-cancel, workspace-data-deletions-cancel, access-requests-create, create, workspace-data-deletions-create, access-requests-decline, delete, data-retention-get, get, workspace-data-deletions-get, members-get-permissions, access-requests-grant, access-requests-list, list, white-label-client-access-list, workspace-data-deletions-list, white-label-client-access-replace, members-replace-permissions, data-retention-update, update

access-requests-cancel

Write. POST https://api.ken.so/v1/access-requests/{accessRequestId}/cancel

Path: accessRequestId

Cancel your own pending access request. Only the member who asked can cancel.

POST /api/v1/access-requests/{accessRequestId}/cancel with Ken-Version
1.1 and X-Ken-Workspace-Id. Public exposure. Someone else's request is
403; one that is no longer pending is 409. Envelope: success plus data.

workspace-data-deletions-cancel

Write. POST https://api.ken.so/v1/workspace-data-deletions/{workspaceDataDeletionId}/cancel

Path: workspaceDataDeletionId

Cancel a scheduled workspace data deletion and resume the campaigns it paused. Internal. Works only while the deletion is scheduled.

POST /api/v1/workspace-data-deletions/{workspaceDataDeletionId}/cancel.
Internal. Sends Ken-Version 1.1. Needs the members feature. Works with the
data_controls flag off, so a deletion scheduled before the flag was turned off
can still be canceled.

Returns the deletion with status canceled and canceledAt. A deletion that is
running, completed, canceled or failed answers 409 invalid_state. Only the
campaigns this deletion paused, and that are still paused, resume.

access-requests-create

Write. POST https://api.ken.so/v1/access-requests

Body (json): key string, kind string, level string, reason string

Ask the workspace's admins for a page, a feature, or more credits. kind is page, feature or credits; key names the page or feature.

POST /api/v1/access-requests with Ken-Version 1.1 and
X-Ken-Workspace-Id. Public exposure. Any member may ask.

kind=page: key is a page (today, inbox, meetings, accounts, campaigns,
search, workflows, studio, knowledge, share, delivery); level is view or
edit, omitted = one level above what you have. kind=feature: key is a
feature (approve ... workspace_settings). kind=credits: key is
monthly_limit. reason is an optional note up to 2000 characters.

A new request is HTTP 201; an open request for the same thing is returned
as 200. Envelope: success plus data.

create

Write. POST https://api.ken.so/v1/permission-templates

Body (json): description string, name string, permissions any JSON, sourceMemberId integer

Create a custom permission template, or save a member's access as one. Pass permissions, or source_member_id to save that member's access. Not both.

POST /api/v1/permission-templates with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. Requires the members permission.

permissions: {pages: {campaigns: "edit"}, features: ["approve"],
accountScope: "all"|"own", monthlyCreditLimit: 2000|null}. Pages left out
are off, features left out are off, accountScope defaults to all and
monthlyCreditLimit to no limit. Pages: today, inbox, meetings, accounts,
campaigns, search, workflows, studio, knowledge, share, delivery (off, view,
edit). Features: approve, launch, reply, share, ask, import, export, members,
billing, integrations, white_label, workspace_settings.

source_member_id ("Save as template") copies that member's effective
permissions, and the member moves onto the new template with overrides
cleared. Saving yourself is 403 cannot_change_own_permissions. A member the
members list does not show is not_found.

Names are unique per workspace and the built-in names are reserved
(400 validation_failed); a taken name is 409 conflict. HTTP 201.

workspace-data-deletions-create

Write. POST https://api.ken.so/v1/workspace-data-deletions

Body (json): confirmation string

Schedule deletion of ALL data in the workspace, 24 hours from now. Destructive. Only call it after the user typed DELETE ALL DATA themselves.

POST /api/v1/workspace-data-deletions with body {confirmation}. Internal.
Sends Ken-Version 1.1. Needs the members feature (an admin); a
Client seat is refused. 404 while the data_controls flag is off.

confirmation must be exactly DELETE ALL DATA. Never fill it in yourself:
ask the user to type it, and pass what they typed. Anything else fails here
before the request, and the API answers 400 validation_failed on
confirmation.

Effect: every campaign that could send in the next 24 hours is paused now.
At dueAt Kenso deletes every campaign, contact, account, champion, reply,
outbound event, Studio page, Knowledge file, meeting (with its recording and
notes), booking and Ken chat in the workspace. The workspace, its members,
inboxes, domains, billing and connected integrations stay, with what they sync
(calendar events, the LinkedIn network, the CRM record map). Returns 201 with the deletion. While one is
already scheduled or running it returns 200 with that one and changes
nothing. Campaign launch and resume answer 409 invalid_state, and approved
account touches do not send, until the deletion is canceled. Undo with
workspace-data-deletions-cancel before dueAt.

access-requests-decline

Write. POST https://api.ken.so/v1/access-requests/{accessRequestId}/decline

Path: accessRequestId

Decline a pending access request. Requires the members permission.

POST /api/v1/access-requests/{accessRequestId}/decline with Ken-Version
1.1 and X-Ken-Workspace-Id. Internal exposure. A request that is no
longer pending is 409. Envelope: success plus data.

delete

Write. DELETE https://api.ken.so/v1/permission-templates/{templateId}

Path: templateId

Delete a custom permission template. Its members move to Viewer. data.movedMembers counts the members that moved.

DELETE /api/v1/permission-templates/{templateId} with Ken-Version 1.1
and X-Ken-Workspace-Id. Internal exposure. Requires the members
permission. Built-in templates cannot be deleted. Envelope: success plus
data {movedMembers}.

data-retention-get

Read. GET https://api.ken.so/v1/data-retention

Return how many months the workspace keeps leads, replies and activity, or Never. Internal. Any member of the workspace.

GET /api/v1/data-retention. Internal. Sends Ken-Version 1.1. The workspace is
X-Ken-Workspace-Id. data.months is a whole number from data.minMonths (1) to
data.maxMonths (120), or null for Never (Kenso keeps the data until someone deletes it).
data.allowedMonths are the presets (6, 12, 24, 36); any other value is a custom
period. A workspace that never changed it is on Never and has no updatedAt. Readable
whatever the data_controls flag.

get

Read. GET https://api.ken.so/v1/permission-templates/{templateId}

Path: templateId

Return one permission template. template_id comes from api_permission_templates_list.

GET /api/v1/permission-templates/{templateId} with Ken-Version 1.1 and
X-Ken-Workspace-Id. Public exposure. Any member may read. A template
of another workspace is 404. Envelope: success plus data.

workspace-data-deletions-get

Read. GET https://api.ken.so/v1/workspace-data-deletions/{workspaceDataDeletionId}

Path: workspaceDataDeletionId

Return one workspace data deletion. Internal. Same row shape as workspace-data-deletions-list.

GET /api/v1/workspace-data-deletions/{workspaceDataDeletionId}. Internal.
Sends Ken-Version 1.1. 404 when the id is not in the workspace.

members-get-permissions

Read. GET https://api.ken.so/v1/members/{memberId}/permissions

Path: memberId

Return a member's template, overrides and effective permissions. member_id is the Kenso user id.

GET /api/v1/members/{memberId}/permissions with Ken-Version 1.1 and
X-Ken-Workspace-Id. Public exposure. Any member reads their own;
someone else's needs the members permission (403 otherwise), and a user
the members list does not show is not_found. data:
template {id, name, builtIn}, overrides (only the differences from the template), effective
(all eleven pages, features, accountScope, monthlyCreditLimit) and
changeCount. Envelope: success plus data.

access-requests-grant

Write. POST https://api.ken.so/v1/access-requests/{accessRequestId}/grant

Path: accessRequestId

Body (json): level string, monthlyLimit integer

Grant a pending access request. Credits requests need monthly_limit, or no_limit=true for no limit.

POST /api/v1/access-requests/{accessRequestId}/grant with Ken-Version 1.1
and X-Ken-Workspace-Id. Internal exposure. Requires the members
permission.

Page requests: level (view or edit) grants a different level than asked.
Credits requests: monthly_limit is the person's credits per calendar month
(0 = cannot spend); no_limit=true sends monthlyLimit null (no limit).
A request that is no longer pending is 409. Envelope: success plus data.

access-requests-list

Read. GET https://api.ken.so/v1/access-requests

Query: cursor string, limit integer, status string

List access requests: all of them with members, else your own. status filters to pending, granted, declined or canceled.

GET /api/v1/access-requests with Ken-Version 1.1 and X-Ken-Workspace-Id.
Public exposure. A member with the members permission sees every
request in the workspace; anyone else sees their own.

limit is 1..100 (backend default 50). cursor is pagination.nextCursor.
Envelope: success, data array, pagination.

list

Read. GET https://api.ken.so/v1/permission-templates

List the workspace's permission templates, built-in and custom. Each has pages, features, accountScope, monthlyCreditLimit and memberCount.

GET /api/v1/permission-templates with Ken-Version 1.1 and
X-Ken-Workspace-Id. Public exposure. Any member may read. Built-ins
(Admin, Editor, Viewer, Client) come first; builtIn is null for a custom
template, and locked is true for Admin. Behind the backend 'permissions'
flag: 404 while it is off. Envelope: success, data array, pagination.

white-label-client-access-list

Read. GET https://api.ken.so/v1/white-label/client-access

List who reaches which client workspace of the current master workspace. Master workspace only; needs the white-label and members permissions.

GET /api/v1/white-label/client-access with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. Behind the permissions feature flag
(404 not_found while it is off). A client workspace is 403
white_label_master_only; needs the white_label and members permissions.

data.members: every member of the master with memberId, email, role,
scope (none, all or selected), templateKey, childWorkspaceIds (the chosen
ones for selected) and reachableChildWorkspaceIds (the client workspaces
they hold a membership in now). data.childWorkspaces: every client
workspace with childWorkspaceId, name and members, each with source
(grant or manual) and isMasterMember. Kenso staff are listed only for staff
callers. Envelope: success plus data.

workspace-data-deletions-list

Read. GET https://api.ken.so/v1/workspace-data-deletions

Query: cursor string, limit integer, status string

List the workspace's data deletions, newest first. Internal. Shows whether one is scheduled and when it is due.

GET /api/v1/workspace-data-deletions. Internal. Sends Ken-Version 1.1. The
workspace is X-Ken-Workspace-Id (client_id). Needs the members
feature. Works with the data_controls flag off.

status filters by a comma list (OR): scheduled, running, completed, canceled,
failed. limit is 1 to 200 (server default 50); cursor continues from
pagination.nextCursor while pagination.hasMore is true.

Each row: id, status, requestedAt, dueAt (requestedAt + 24 hours),
requestedByUserId, canceledAt, completedAt (absent when not set).

white-label-client-access-replace

Write. PUT https://api.ken.so/v1/white-label/client-access/{memberId}

Path: memberId

Body (json): childWorkspaceIds array, scope string, templateKey string

Replace a master member's access to the client workspaces. scope none, all or selected; template_key admin, editor or viewer. Master workspace only; needs the white-label and members permissions.

PUT /api/v1/white-label/client-access/{memberId} {scope, childWorkspaceIds,
templateKey} with Ken-Version 1.1 and X-Ken-Workspace-Id. Internal
exposure. Behind the permissions feature flag (404 not_found while it is
off). A client workspace is 403 white_label_master_only; needs the
white_label and members permissions.

Replace semantics. member_id is the Kenso user id of a member of the master.
scope all covers every client workspace, later ones included; selected
covers child_workspace_ids (1 to 1,000, only with selected); none removes
the grant. template_key is admin, editor or viewer; left out, a live grant
keeps its template and a new grant gets editor.

The save writes ordinary memberships: a missing one is added with the
template, one added by hand stays as it is (manualChildWorkspaceIds), one
the grant made gets the new template when it changed (its overrides are
cleared), and one the grant made on a client workspace that left the set is
removed. A member who is the last Admin of a client workspace keeps that
membership and the workspace is reported in refused (code last_admin);
the owner of a client workspace keeps their membership and template there
unless the caller is that owner (code owner_protected).
Saving the same body again changes nothing. The master's grant wins: a save
adds back a grant membership someone removed inside a client workspace, so
to keep a member out of one client, take it out of the grant.

An id that is not a client workspace of this master is 400
validation_failed with one error.details entry per id (code not_found), and
nothing is written. Changing your own access is 403
cannot_change_own_permissions unless you are Kenso staff. A user who is not a
member of the workspace is 404 not_found.

data: memberId, scope, templateKey, childWorkspaceIds,
addedChildWorkspaceIds, updatedChildWorkspaceIds, removedChildWorkspaceIds,
manualChildWorkspaceIds and refused [{childWorkspaceId, code, message}].

members-replace-permissions

Write. PUT https://api.ken.so/v1/members/{memberId}/permissions

Path: memberId

Body (json): overrides any JSON, templateId integer

Set a member's template and overrides (replace: omitted overrides are cleared). Read api_members_get_permissions first and send back every override to keep.

PUT /api/v1/members/{memberId}/permissions with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. Requires the members permission.

Replace semantics: the body is {templateId, overrides}, and omitting
overrides (sent as {}) clears every override. overrides: {pages:
{campaigns: "view"}, features: {billing: true}, accountScope: "own"|null,
credits: {monthlyLimit: 2000|null}|null}. An override equal to the
template's value is dropped. template_id is any template of the workspace,
built-in or custom.

A user the members list does not show is not_found, and nothing changes.
Changing your own permissions is 403 cannot_change_own_permissions; moving
the last Admin off Admin is 409 last_admin. While the permissions flag is
on, moving the workspace owner (isOwner true on the member) off Admin or
giving them overrides is 409 owner_protected unless the caller is the
owner or Kenso staff. Envelope: success plus data.

data-retention-update

Write. PATCH https://api.ken.so/v1/data-retention

Body (json): months integer

Change how many months the workspace keeps leads, replies and activity, or set Never. Change it only when the user asks: once the nightly purge is on, data older than the period is deleted for good. Requires the members permission (workspace admins).

PATCH /api/v1/data-retention. Internal. Sends Ken-Version 1.1. The workspace is
X-Ken-Workspace-Id. months is a whole number from 1 to 120 (presets 6, 12, 24, 36;
any other is a custom period) or "never", sent as null: Kenso keeps the data until
someone deletes it and the purge skips the workspace. Anything else fails here and
with 400 validation_failed on the server. A period means the nightly purge deletes
contacts, email messages, contact activities and activity events older than it, with
no undo (contacts on a campaign that is scheduled, launching, sending or paused
stay, with their replies and activity). The same value again saves nothing. A change
writes the audit line "Set data retention to N months" (or "to Never"). 404 not_found
while the data_controls flag is off for the workspace; 403 forbidden without the
members permission, for a Client seat, or for a credential with no member.

update

Write. PATCH https://api.ken.so/v1/permission-templates/{templateId}

Path: templateId

Body (json): description string, name string, permissions any JSON

Change a permission template. Absent fields stay unchanged. permissions.pages merges page by page; permissions.features replaces the list.

PATCH /api/v1/permission-templates/{templateId} with Ken-Version 1.1 and
X-Ken-Workspace-Id. Internal exposure. Requires the members permission.

name and description change only on custom templates. The Admin template is
locked. permissions takes the same keys as permissions(operation="create").
Every member on the template gets the change. Envelope: success plus data.