Grant access
curl --request POST \
--url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/access \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"principal_id": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({principal_id: '<string>'})
};
fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/access', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/access"
payload = { "principal_id": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "knowledge_base.access_binding",
"knowledge_base_id": "<string>",
"principal_type": "user",
"principal_id": "<string>",
"role": "owner",
"created_at": 123,
"email": "<string>",
"org_slug": "<string>",
"granted_by": "<string>",
"updated_at": 123
}Access
Grant access
Idempotent on (knowledge_base_id, principal_type, principal_id): re-granting updates the role (200) instead of
duplicating. Requires admin+ (or owner).
POST
/
v1
/
knowledge_bases
/
{knowledgeBaseId}
/
access
Grant access
curl --request POST \
--url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/access \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"principal_id": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({principal_id: '<string>'})
};
fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/access', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/access"
payload = { "principal_id": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "knowledge_base.access_binding",
"knowledge_base_id": "<string>",
"principal_type": "user",
"principal_id": "<string>",
"role": "owner",
"created_at": 123,
"email": "<string>",
"org_slug": "<string>",
"granted_by": "<string>",
"updated_at": 123
}Authorizations
User session JWT or instance API key (iak_*). Send as Authorization: Bearer <token>.
Path Parameters
Knowledge base id. Legacy physical prefix vs_ (the kb_ rename is deferred).
Maximum string length:
128Pattern:
^vs_[A-Za-z0-9-]+$Body
application/json
Response
Existing binding updated.
Per-knowledge-base access binding, persisted in the
platform-managed product_bindings store (storage owns no
bindings collection). Principals: user, group, org, and
agent - agent ownership is first-class (§F-6). The owner
appears as an explicit role: owner binding; admin / editor
/ reader are grantable via the API (owner is not).
Available options:
knowledge_base.access_binding Pattern:
^vs_[A-Za-z0-9-]+$Available options:
user, group, org, agent Maximum string length:
128Available options:
owner, admin, editor, reader Resolved at read time for user principals.
Was this page helpful?