Each kind of knowledge base has its own API, and both take the same API keys:
Create an API Key #
Only the workspace owner and admins can create, view, and delete keys.
In Knowledge, click Service API in the top-right corner, then API Key. Each workspace can have up to 10 keys.
The same panel shows the Service API endpoint, the base URL for both APIs.
Choose a Scope #
When you create a key, give it access to all knowledge bases, or only to the ones you pick, of either kind. Pick only the knowledge bases the integration works with.
If it also calls operations that name no knowledge base, such as listing or creating classic knowledge bases, managing tags, or getting the available models, give it access to all knowledge bases instead.
The scope can’t be changed later. To change it, replace the key.
Replace a Key #
To change a key’s scope, or to rotate it, create the new key, switch your integration to it, then delete the old one. A deleted key stops working right away.
On agent knowledge bases, research tasks and deletion jobs can be read only with the key that started them. Before you delete the old key, let them finish and read their results.
When a Key Is Refused #
| Cause | Classic knowledge base | Agent knowledge base |
|---|---|---|
| The knowledge base is outside the key’s scope | 403 forbidden | 403 knowledge_fs_access_denied |
| A scoped key calls an operation that names no knowledge base | 403 forbidden | 403 forbidden |
| API access was turned off for the knowledge base | 403 forbidden | 403 knowledge_fs_access_denied |
| The key was deleted, directly or along with the only knowledge base it covered | 401 unauthorized | 401 unauthorized |
| On Dify Cloud, the workspace reached its request rate limit | 403 forbidden | 403 forbidden |
On a classic knowledge base, a 403 forbidden can have several of these causes, so read the error’s message to tell them apart.
A key scoped to a classic knowledge base doesn’t cover the agent knowledge base upgraded from it. To reach the agent one, replace the key with one that includes it.
An agent knowledge base ID that doesn’t exist in the key’s workspace returns 401 knowledge_fs_invalid_credential, as a bad key would. Check the ID before you replace the key.