> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Share Knowledge base access

> Grant, change, or revoke Knowledge base access for people and workspace API keys

Grants, changes, or revokes access on an existing Knowledge base. Targets are people and workspace API keys. Groups stay on the in-app [Share Knowledge bases with the API](/en/developer/knowledge-folder-api/sharing) flow.

## Before You Start

* **API key scope**: Requires an API key with the `KNOWLEDGE_FOLDER_API` scope. The API key itself needs the Editor role on the Knowledge base. See [Share Knowledge bases with the API](/en/developer/knowledge-folder-api/sharing) for setup instructions.
* **Knowledge bases**: The Knowledge Folder API manages resources that appear as Knowledge bases in the Library.

## Base URL

```
https://api.langdock.com
```

<Warning>
  **Dedicated deployments**

  Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.
</Warning>

## Roles

| API value | Library label | Access                                           |
| --------- | ------------- | ------------------------------------------------ |
| `USER`    | Viewer        | Search and retrieve files                        |
| `EDITOR`  | Editor        | Upload, update, delete, share access, and rename |

A Viewer-only key, including a key that only has API search through the Knowledge base, cannot call these endpoints.

An Editor workspace key can grant other qualifying workspace keys even if the key owner is not a workspace admin. The in-app Share dialog still lists API keys only for workspace admins.

## Grant access

`POST /knowledge/{folderId}/access`

### Path Parameters

| Parameter  | Type   | Required | Description                  |
| ---------- | ------ | -------- | ---------------------------- |
| `folderId` | string | Yes      | The ID of the Knowledge base |

### Request Body

| Field       | Type      | Required | Description                                                                |
| ----------- | --------- | -------- | -------------------------------------------------------------------------- |
| `targetIds` | string\[] | Yes      | User IDs and workspace API key IDs to grant. Minimum: `1`. Maximum: `100`. |
| `role`      | string    | Yes      | `USER` or `EDITOR`                                                         |

All IDs must resolve to a human workspace member or a qualifying workspace API key. Group IDs are not accepted. Personal API keys are not eligible. If any ID is missing or ineligible, the request fails and no grants are written.

### Grant with cURL

```bash theme={null}
curl -X POST "https://api.langdock.com/knowledge/{folderId}/access" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetIds": [
      "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "role": "EDITOR"
  }'
```

### Grant with JavaScript

```javascript theme={null}
const axios = require("axios");

async function grantAccess(folderId, targetIds, role) {
  const response = await axios.post(
    `https://api.langdock.com/knowledge/${folderId}/access`,
    { targetIds, role },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
    }
  );

  return response.data;
}

const result = await grantAccess(
  "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  ["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
  "EDITOR"
);
console.log(result.result.granted);
```

### Success Response (200 OK)

```json theme={null}
{
  "status": "success",
  "result": {
    "granted": [
      {
        "type": "USER",
        "targetId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "role": "EDITOR"
      },
      {
        "type": "API_KEY",
        "targetId": "550e8400-e29b-41d4-a716-446655440000",
        "role": "EDITOR"
      }
    ]
  }
}
```

## Change a role

`PATCH /knowledge/{folderId}/access`

| Field      | Type   | Required | Description                        |
| ---------- | ------ | -------- | ---------------------------------- |
| `type`     | string | Yes      | `USER` or `API_KEY`                |
| `targetId` | string | Yes      | The person or workspace API key ID |
| `role`     | string | Yes      | `USER` or `EDITOR`                 |

You cannot change the Knowledge base owner's access. Reassign ownership in the Library first. If the target has no grant yet, this request creates one.

```bash theme={null}
curl -X PATCH "https://api.langdock.com/knowledge/{folderId}/access" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "API_KEY",
    "targetId": "550e8400-e29b-41d4-a716-446655440000",
    "role": "USER"
  }'
```

```json theme={null}
{
  "status": "success"
}
```

## Revoke access

`DELETE /knowledge/{folderId}/access`

| Field      | Type   | Required | Description                        |
| ---------- | ------ | -------- | ---------------------------------- |
| `type`     | string | Yes      | `USER` or `API_KEY`                |
| `targetId` | string | Yes      | The person or workspace API key ID |

You cannot revoke the Knowledge base owner's access.

```bash theme={null}
curl -X DELETE "https://api.langdock.com/knowledge/{folderId}/access" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "API_KEY",
    "targetId": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

```json theme={null}
{
  "status": "success"
}
```

## Error Handling

| Status | Meaning                                                                               |
| ------ | ------------------------------------------------------------------------------------- |
| `400`  | Invalid body, ineligible share target, or owner access change                         |
| `401`  | Invalid or missing API key                                                            |
| `403`  | Missing `KNOWLEDGE_FOLDER_API` scope, or the key is not Editor on this Knowledge base |
| `404`  | Knowledge base or access target not found                                             |
| `429`  | Rate limit exceeded                                                                   |
| `500`  | Unexpected server error                                                               |

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>


## OpenAPI

````yaml post /knowledge/{folderId}/access
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
    description: Production
security:
  - bearerAuth: []
paths:
  /knowledge/{folderId}/access:
    post:
      summary: Grant Knowledge base access to people or workspace API keys
      parameters:
        - name: folderId
          in: path
          required: true
          description: The ID of the knowledge folder
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - targetIds
                - role
              properties:
                targetIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  minItems: 1
                  maxItems: 100
                role:
                  type: string
                  enum:
                    - USER
                    - EDITOR
      responses:
        '200':
          description: Access granted successfully
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````